Frontend Developer Onboarding

Welcome to the Daitics engineering team. This guide will take you from zero to productive on the DTX Portal — the frontend application powering the Daitics AI CDP platform. Follow this structured 7-day program, complete the checklist, and prepare your reverse presentation.

---

Onboarding Timeline

---

Prerequisites

Before your first day, ensure you have the following installed and configured.

Requirement	Version	Verify
Node.js	22+	node -v
pnpm	10.16+	pnpm -v
Git	Latest	git --version
VS Code	Latest	—
Docker	Latest (optional)	docker --version

Recommended VS Code Extensions

Extension	Purpose
ESLint	Linting (flat config, no Prettier)
Tailwind CSS IntelliSense	Class autocomplete and hover preview
Pretty TypeScript Errors	Readable TS error messages
Thunder Client or REST Client	API testing
GitLens	Git history and blame
Error Lens	Inline error/warning display

Access Requirements

• GitHub access to daitics-com/dtx-portal repository
• Keycloak credentials for local development
• VPN access (if remote)
• Jira/Linear board access for task tracking

---

Day 1: Environment Setup

Goal: Clone the repo, install dependencies, run the dev server, and verify the app loads.

Step 1 — Clone and Install

git clone git@github.com:daitics-com/dtx-portal.git
cd dtx-portal
pnpm install

Step 2 — Environment Configuration

Copy the example environment file and configure it:

cp apps/portal/.env.example apps/portal/.env.local

Key variables to set:

Variable	Description	Example
VITE_API_BASE_URL	API gateway URL	http://localhost:8080
VITE_KEYCLOAK_URL	Keycloak auth server	http://localhost:8180
VITE_KEYCLOAK_REALM	Auth realm	daitics
VITE_KEYCLOAK_CLIENT_ID	OAuth client ID	dtx-portal

Step 3 — Run the Dev Server

pnpm dev

The app starts at http://localhost:3000. Vite proxies API calls:

• /api/* forwards to localhost:8080 (API Gateway)
• /sdg-api/* forwards to localhost:50032 (Synthetic Data)

Step 4 — Verify

• App loads without errors
• Login page appears (Keycloak redirect)
• After login, the dashboard renders

tip

If backend services aren't running locally, ask the team for the DEV environment URL and update your .env.local to point there.

Useful Commands

pnpm dev          # Start dev server
pnpm build        # TypeScript check + production build
pnpm lint         # ESLint check
pnpm test         # Run Vitest
pnpm test:ui      # Vitest visual dashboard

---

Day 2: Architecture Deep Dive

Goal: Understand the monorepo structure, import conventions, and how the pieces fit together.

Monorepo Layout

Import Aliases

Alias	Resolves To	Usage
@/	apps/portal/src/	Portal app code
@dtx/ui	packages/ui/src	Shared UI components
@dtx/utils	packages/utils/src	Shared utilities (cx(), formatBytes(), debounce())

info

@dtx/ui is source-linked — no build step required. You import TypeScript directly from the package source.

Key Configuration Files

File	Purpose
pnpm-workspace.yaml	Workspace definitions + centralized dependency catalog
apps/portal/vite.config.ts	Vite config, dev proxy, manual chunk splitting
apps/portal/tsconfig.json	TypeScript strict mode, path aliases
eslint.config.js	ESLint 9 flat config (no Prettier)
apps/portal/src/config/env.ts	Centralized env variable typing

Explore These Directories

Spend time browsing each directory. Read 2-3 files in each to understand the patterns:

1. apps/portal/src/router/router.tsx — All 27+ routes
2. apps/portal/src/services/ — Pick any service, trace from component to API call
3. apps/portal/src/stores/ — Read usePipelineStore to understand Zustand patterns
4. packages/ui/src/components/base/ — See how base components wrap React Aria

---

Day 3: Core Technologies

Goal: Understand the key technology choices and how they integrate.

Technology Stack

React 19

The project uses React 19 features. Key patterns:

• Functional components only (no class components)
• Hooks everywhere (useState, useEffect, useMemo, useCallback)
• Context for cross-cutting concerns (auth, theme)

TypeScript 5.7 (Strict Mode)

• Strict mode is enabled — all types must be explicit at boundaries
• Shared types live in src/types/{feature}.types.ts
• API response types are defined per service

Vite 7

• Native Tailwind CSS plugin (no PostCSS configuration)
• Dev proxy configured in vite.config.ts for backend services
• Manual chunk splitting for optimized loading: react, query, monaco, d3, react-flow

Tailwind CSS 4

• Uses @theme block in CSS instead of tailwind.config.js
• 1,400+ CSS custom properties for the design system
• tailwindcss-react-aria-components for state variant integration
• Class-variance-authority (CVA) for component variant definitions

---

Day 4: State Management & Data Flow

Goal: Understand where data lives and how it flows through the application.

Data Flow Architecture

State Management Strategy

Layer	Tool	Purpose	Persistence
Server state	React Query	API data (pipelines, schemas, operators)	In-memory (lost on refresh)
Local UI state	Zustand	Canvas state, filters, preview data	IndexedDB / localStorage / sessionStorage
Form state	React Hook Form + Zod	User input, validation	None (component lifecycle)
Auth state	Keycloak JS	Tokens, user session	Managed by Keycloak

Zustand Stores (4 Total)

Store	Backend	Key	Scope
usePipelineStore	IndexedDB	dtx-pipeline-autosave	Survives refresh + crashes
useWorkflowDesignerStore	localStorage	workflow-designer-storage	Survives refresh
useAccessManagementStore	sessionStorage	dtx-access-management	Current tab only
usePreviewDataStore	In-memory	—	Component lifecycle

React Query Patterns

// Fetching data
const { data, isLoading } = useQuery({
  queryKey: ['pipelines'],
  queryFn: () => pipelineService.getAll(),
});

// Mutating data
const mutation = useMutation({
  mutationFn: (data) => pipelineService.create(data),
  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['pipelines'] }),
});

Configuration: staleTime: 0 (always refetch), retry: 1.

Authentication Flow (Keycloak)

1. App loads, AuthProvider initializes Keycloak
2. User redirected to Keycloak login (OAuth2 + PKCE)
3. On success, JWT stored in Keycloak JS client
4. fetchWithAuth() injects Authorization: Bearer {token} on every API call
5. Token refreshed automatically every 60 seconds
6. Tenant ID extracted from JWT tenant_id claim

warning

There are no route-level auth guards — all routes require authentication. If the token is missing or expired, fetchWithAuth() triggers a re-login.

---

Day 5: Component Library & Design System

Goal: Understand the UI component hierarchy, theming, and how to build interfaces.

Component Hierarchy

Layer	Package	Examples
Primitives	React Aria Components	Accessible base behavior (focus, keyboard, ARIA)
Base Components	@dtx/ui/base/	Button, Input, Badge, Card, Select, ComboBox
Application Components	@dtx/ui/application/	Table, Modal, Dialog, Tabs, Pagination, DatePicker
Chart Components	@dtx/ui/charts/	LineChart, BarChart, PieChart (Recharts wrappers)
Shared Portal	apps/portal/src/components/shared/	Layout, Header, Sidebar, FormRenderer, DesignerCanvas
Feature Components	apps/portal/src/components/{feature}/	Feature-specific UI (pipelines, schema-registry, etc.)

Design Tokens

The theme system uses 1,400+ CSS custom properties defined in apps/portal/src/styles/theme.css:

Category	Examples
Brand	--color-brand-500 (purple rgb(158 119 237))
Text	--color-text-primary, --color-text-secondary, --color-text-disabled
Background	--color-bg-primary, --color-bg-brand, --color-bg-error
Border	--color-border-primary, --color-border-brand
Radius	--radius-xxs (2px) through --radius-full (9999px)
Shadows	7 levels: xs through 3xl

Typography

Token	Size	Usage
Display 2xl	72px	Hero sections
Display lg	48px	Page titles
Text xl	20px	Section headings
Text md	16px	Body text (default)
Text sm	14px	Secondary text
Text xs	12px	Captions, labels

Font families: Inter (body + display), Roboto Mono (monospace/code).

Icons

The project uses @untitledui/icons (0.0.19) with 100+ icons organized by category: navigation, users, data, pipeline, infrastructure, actions, status, and UI.

Dark Mode

• Class-based toggle via .dark-mode CSS class
• Monaco Editor has dual themes: expression-light and expression-dark
• Not fully rolled out across all components yet

---

Day 6: Feature Development Workflow

Goal: Learn the patterns for building new pages, components, and integrating with APIs.

Naming Conventions

Entity	Pattern	Example
Components	PascalCase	CreateGeneratorWizard.tsx
Pages	PascalCase + Page	UsersPage.tsx
Hooks	use + camelCase	useSyntheticData.ts
Services	camelCase + .service.ts	pipeline.service.ts
Types	camelCase + .types.ts	synthetic-data.types.ts
Stores	use + Name + Store	usePipelineStore.ts
Folders	kebab-case	schema-registry/

Adding a New Page

1. Create a page component in apps/portal/src/pages/:

   export default function MyFeaturePage() {
     return <div>My Feature</div>;
   }
2. Add a route in apps/portal/src/router/router.tsx
3. Update constants/navigation.ts if it needs a sidebar entry
4. The Layout wrapper is auto-included by the router

Creating a Component

1. Add component to apps/portal/src/components/{feature-name}/
2. Use @dtx/ui base components for primitives
3. Use React Query for server data (useQuery / useMutation)
4. Use React Hook Form + Zod for forms
5. Define types in types/{feature}.types.ts
6. Export from the feature folder's index

Calling a Backend API

The project uses a singleton service pattern:

1. React Query hook calls the service method
2. Service class (singleton via getInstance()) makes the HTTP call
3. fetchWithAuth() injects the JWT Authorization header
4. parseApiResponse<T>() unwraps the StandardApiResponse<T> wrapper
5. Response auto-converts snake_case keys to camelCase

Error Handling

Status	Behavior
422	ApiError with fieldErrors[] — maps to form field validation
401/403	Token refresh or re-login
Other	Global error boundary catches render errors; toast for API errors

Form Patterns

• React Hook Form for all forms
• Zod schemas for validation
• Multi-step wizards: parent useForm(), steps use useFormContext()
• Dynamic FormRenderer supports 20+ field types (text, select, mapping, schema-aware, etc.)

---

Day 7: Advanced Features

Goal: Understand the most complex parts of the application.

Pipeline Designer

The pipeline designer is the core feature — a full-screen visual canvas for building data pipelines.

Key concepts:

• XYFlow (@xyflow/react) powers the canvas with zoom, pan, node/edge rendering
• @dagrejs/dagre handles automatic DAG layout
• Operators have categories: SOURCE, SINK, PROCESSOR, TESTER
• OperatorConfigPanel is a multi-stage wizard (Info, Input, Logic, Output, Config, Rejection, Preview)
• Monaco Editor provides full IDE-like editing for SQL expressions
• State persists in IndexedDB via usePipelineStore (survives crashes)

Workflow Designer

A second XYFlow canvas for approval workflows:

• 11 node types: approval, condition, parallel split/join, timer, script, reject, loop, etc.
• Task inbox with claim/complete/delegate actions
• State in localStorage via useWorkflowDesignerStore

8 Backend Microservices

Service	Port	Purpose
API Gateway	8080	Auth, users, roles
Operator Service	50001	Templates, defaults, validation
Pipeline Service	50002	CRUD, compile, deploy, status
Observability	50010	Metrics, logs, traces, WebSocket
Schema Registry	50031	Schema CRUD, versions, PII tagging
Synthetic Data	50032	Generators, pools, universes
Kafka Service	50034	Topics, messages, consumer groups
Cache Service	50035	Key scan, get/set/delete, TTL

Other Advanced Features

Feature	Key Technology	Location
Synthetic Data Generator	5-step wizard, React Hook Form	components/synthetic-data/
Schema Registry	CRUD + versioning, PII tagging	components/schema-registry/
Kafka Management	Topic browsing, message inspection	components/kafka/
Cache Management	Redis/Dragonfly key browser	components/cache/
Observability	WebSocket streaming, Recharts	components/observability/
Access Management	RBAC, Keycloak integration	components/access-management/

---

Onboarding Checklist

Use this checklist to track your progress. Complete all items before your reverse presentation.

Environment

• Repository cloned and dependencies installed
• Environment variables configured
• Dev server running and app accessible
• VS Code extensions installed
• Access to all required systems (GitHub, Keycloak, Jira/Linear)

Codebase Understanding

• Can explain the monorepo structure (apps/portal, packages/ui, packages/utils)
• Understand import aliases (@/, @dtx/ui, @dtx/utils)
• Read router.tsx and can list the major route sections
• Browsed 3+ feature component directories
• Read 2+ service files and understand the singleton pattern
• Read at least 1 Zustand store and understand persistence strategy

Technology Proficiency

• Can explain the difference between Zustand, React Query, and React Hook Form roles
• Understand how fetchWithAuth() handles authentication
• Know how parseApiResponse() transforms backend responses
• Can explain the CVA pattern for component variants
• Understand the Tailwind CSS 4 @theme block approach

Practical Skills

• Created a simple page and added a route
• Used @dtx/ui components (Button, Input, Table, Modal)
• Fetched data from a backend API using React Query
• Created a form with React Hook Form + Zod validation
• Ran tests with pnpm test
• Ran the linter with pnpm lint and fixed any issues

Error Handling & Testing

• Understand how API errors flow through parseApiResponse() to toasts or form errors
• Know how 422 validation errors map to React Hook Form fields
• Can explain the error boundary strategy (global vs. feature-level)
• Read the Testing Guide and understand test patterns
• Read the Error Handling Patterns doc

Workflow & Process

• Understand the git branching strategy (feature/fix/refactor branches)
• Know the PR checklist and code review expectations
• Familiar with debugging tools (React DevTools, Network tab, React Query DevTools)
• Read the Development Workflow and troubleshooting section

Advanced (Stretch Goals)

• Explored the Pipeline Designer canvas (added/connected nodes)
• Read the OperatorConfigPanel multi-stage wizard code
• Understood how Monaco Editor integrates for SQL editing
• Reviewed the Docker build process and Nginx proxy config

---

Recommended Reading Order

Read the Build documentation in this order for the best learning progression:

Order	Document	Key Topics
1	Build Overview	High-level architecture, tech stack summary
2	Project Structure	Monorepo layout, packages, file organization
3	Development Setup	Environment, tooling, scripts, Docker
4	Pages & Routing	React Router setup, 27+ routes, navigation
5	Components	Component library, @dtx/ui, design patterns
6	State Management	Zustand, React Query, form state, persistence
7	API Integration	Services, fetchWithAuth, error handling
8	UI & Styling	Tailwind, design tokens, theming, typography
9	Architecture Flows	Pipeline designer, workflow canvas, data flows
10	Error Handling Patterns	API errors, form validation, toasts, error boundaries
11	Testing Guide	Vitest, Testing Library, test patterns, mocking
12	Development Workflow	Git, PRs, code review, debugging, troubleshooting

Also review:

• Architecture Decisions — Why Zustand, XYFlow, React Aria, pnpm
• Operator Matrix — Complete operator catalog
• API Overview — Backend service landscape

---

Reverse Presentation

At the end of your first week, prepare a 30-minute presentation for the team covering:

What to Present

1. Architecture Overview (10 min)

   • Draw the monorepo structure from memory
   • Explain the data flow: Component to React Query to Service to Backend
   • Describe the 4 Zustand stores and why each uses different persistence

2. Technology Deep Dive (10 min)

   • Pick one advanced feature (Pipeline Designer, Synthetic Data, or Schema Registry)
   • Walk through the code from the page component to the API call
   • Highlight patterns you found interesting or surprising

3. Questions & Observations (10 min)

   • What patterns did you find effective?
   • What was confusing or could be documented better?
   • Any suggestions for improvement?

Tips for a Strong Presentation

• Use the actual codebase — show real files, not slides
• Trace a complete user journey (e.g., "creating a pipeline from scratch")
• Be honest about what you didn't understand — this helps the team identify documentation gaps
• Prepare 2-3 questions about architectural decisions

tip

The reverse presentation isn't a test — it's a knowledge-sharing exercise. The team learns what's clear and what needs better documentation. Your fresh perspective is valuable.