Development Setup

Prerequisites

Tool	Version	Purpose
Node.js	22+ (Alpine for Docker)	JavaScript runtime
pnpm	10.16.1	Package manager
Git	Latest	Version control

---

Getting Started

# Clone the repository
git clone <repo-url>
cd dtx-portal

# Install dependencies (all workspaces)
pnpm install

# Start development server
pnpm dev
# → http://localhost:3000

The dev server starts Vite with:

• Hot Module Replacement (HMR)
• API proxy to localhost:8080 (gateway)
• SDG API proxy to localhost:50032

---

Available Scripts

Root Level

Script	Command	What it Does
pnpm dev	pnpm --filter portal dev	Start Vite dev server on :3000
pnpm build	pnpm --filter portal build	TypeScript check + Vite production build
pnpm preview	pnpm --filter portal preview	Preview production build locally
pnpm lint	pnpm --filter portal lint	Run ESLint on all TS/TSX
pnpm type-check	pnpm --filter portal type-check	TypeScript check (tsc --noEmit)
pnpm test	pnpm --filter portal test	Run Vitest tests
pnpm test:ui	pnpm --filter portal test:ui	Vitest with visual UI dashboard

UI Package

Script	What it Does
pnpm --filter @dtx/ui build	Type check UI package
pnpm --filter @dtx/ui dev	Watch mode type checking
pnpm --filter @dtx/ui lint	Lint UI package
pnpm --filter @dtx/ui lint:fix	Auto-fix lint issues

---

Dev Server Proxy Configuration

During development, Vite proxies API calls to backend services:

In deployed environments, Nginx handles proxying to all 8 backend services.

---

Linting & Code Quality

ESLint Configuration

Format: ESLint 9 flat config (eslint.config.js)

Plugin	Purpose
@eslint/js	Recommended JS rules
@typescript-eslint	TypeScript-specific rules
eslint-plugin-react-hooks	React Hooks rules
eslint-plugin-react-refresh	HMR compatibility warnings

Key Rules:

• @typescript-eslint/no-unused-vars: error (ignores _ prefixed args)
• react-refresh/only-export-components: warn (for HMR compatibility)
• No Prettier — formatting is handled by ESLint only

---

Testing

Framework

Tool	Version	Purpose
Vitest	3.2.4	Test runner
@testing-library/react	16.3.0	Component testing
@testing-library/jest-dom	6.8.0	DOM assertion matchers
@testing-library/user-event	14.6.1	User interaction simulation
jsdom	27.0.0	Browser environment
@vitest/ui	3.2.4	Visual test dashboard

Configuration

// apps/portal/vitest.config.ts
export default defineConfig({
  plugins: [react()],
  test: {
    globals: true,           // No need to import describe/it/expect
    environment: 'jsdom',    // Browser-like environment
    setupFiles: './src/test/setup.ts',
    css: true,               // Process CSS imports
  },
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
      '@dtx/ui': path.resolve(__dirname, '../../packages/ui/src'),
      '@dtx/utils': path.resolve(__dirname, '../../packages/utils/src'),
    },
  },
});

Status: Testing infrastructure is configured. Test coverage is being built out.

---

Docker Build

Multi-stage build: Node 22 Alpine for building, Nginx Alpine for serving.

# Stage 1: Build
FROM node:22-alpine AS builder
WORKDIR /app
RUN npm install -g pnpm@10.16.1
COPY . .
RUN pnpm install --no-frozen-lockfile
RUN cd apps/portal && pnpm vite build --mode production

# Stage 2: Serve with Nginx
FROM nginx:alpine
COPY --from=builder /app/apps/portal/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 3000
CMD ["nginx", "-g", "daemon off;"]

Nginx Reverse Proxy

Nginx serves static files and proxies API calls to backend services:

Location	Proxies To
/proxy/pipeline/	Pipeline Service :50002
/proxy/operator/	Operator Service :50001
/proxy/schema/	Schema Registry :50031
/proxy/sdg/	SDG Service :50032
/proxy/kafka/	Kafka Service :50034
/proxy/cache/	Cache Service :50035
/proxy/expressions/	Expression Service :50001
/proxy/observability/	Observability :50010
/api/	API Gateway :8080

---

Deployment

Environments

Environment	Server	Port	Container
DEV	100.91.186.89	30000	dtx-portal-dev
TEST	100.110.45.41	30000	dtx-portal-test
Production	TBD	TBD	TBD

Deployment Process

Deploy via shell scripts:

• deploy-dev.sh — Deploy to DEV environment
• deploy-test.sh — Deploy to TEST environment

No CI/CD pipeline is configured yet. Deployments are manual.