nextcraft/.ciagent/ARCHITECTURE.md

Nextcraft — ARCHITECTURE.md

Overview

Nextcraft v0.1 is a high-fidelity UI/UX prototype built as a TypeScript monorepo using pnpm workspaces and turborepo. The prototype consists of a single Next.js application with route groups for each surface (Learner, Marketplace, Employer Dashboard, Admin), backed by a shared component library, typed mock data layer, and shared types package.

No backend, no database, no authentication logic. All data is static/mock. The architecture is designed to be replaced piece-by-piece with real backend services in future milestones.

Confirmed Technology Stack (Research Findings)

Technology	Version	Purpose
Node.js	v24.15.0	Runtime
pnpm	12.3.4	Package manager + workspaces
turborepo	latest	Build orchestration
Next.js	latest (App Router)	Web application framework
React	19+	UI library
TypeScript	5.x	Type system
Tailwind CSS	v4	Utility-first CSS framework
lucide-react	latest	Icon system
recharts	latest	Charts for employer/admin dashboards
@xyflow/react (react-flow)	latest	Competency graph viewer in admin surface
Inter font	via next/font	Typography
ESLint	via Next.js	Linting
Prettier	latest	Code formatting

Architecture Decisions from Research

1. Next.js App Router with route groups — (learner), (marketplace), (employer), (admin) provide clean URL separation without affecting paths
2. Tailwind CSS v4 — Configured via @theme in CSS, no tailwind.config.js needed (v4 paradigm shift). Dark mode via class strategy.
3. Server components by default — All pages are server components. Client components only for interactive elements (filters, search, chat, graph viewer, dark mode toggle)
4. Mock data as ES modules — Typed TS files exported from packages/mock-data. No JSON files — all mock data is programmatically generated for richer structure.
5. react-flow (@xyflow/react) — Confirmed for competency graph viewer. Provides interactive node/edge rendering with built-in controls.
6. recharts — Confirmed for analytics dashboards. Responsive, composable, integrates well with React server components.
7. pnpm workspaces — apps/web + packages/ui + packages/mock-data + packages/types. Shared deps hoisted.

---

Components

apps/web — Next.js Application

Component	Description	Boundaries	Depends On
app/(learner)/	Learner surface route group: landing, catalog, competency stack, dashboard, byte viewer, sandbox mockup, assessment mockup	Learner-only routes and layouts	packages/ui, packages/mock-data, packages/types
app/(marketplace)/	Marketplace surface route group: job board, job detail, employer profile, search/filter, pricing	Marketplace-only routes and layouts	packages/ui, packages/mock-data, packages/types
app/(employer)/	Employer dashboard route group: overview, talent search, candidate profile, posting management	Employer-only routes and layouts	packages/ui, packages/mock-data, packages/types
app/(admin)/	Admin surface route group: overview, learner management, competency graph viewer, moderation	Admin-only routes and layouts	packages/ui, packages/mock-data, packages/types
app/layout.tsx	Root layout: theme provider, navigation shell, responsive container	All routes	packages/ui
components/	Surface-specific components (not shared across surfaces)	Per-surface only	packages/ui

packages/ui — Shared Component Library

Component	Description	Boundaries	Depends On
design-tokens/	CSS custom properties: color palette, typography scale, spacing system, breakpoints, shadows, radii	Foundation layer — no dependencies	None
primitives/	Button, Input, Card, Badge, Avatar, Dialog, Tabs, Progress, Tooltip, Skeleton, Toast	Atomic UI components	design-tokens
composites/	Navigation, Table, SearchBar, FilterPanel, ChatInterface, GraphViewer, ArtifactCard, CompetencyBadge, JobCard, CandidateCard, MetricCard	Composite components built from primitives	primitives, packages/types
layouts/	Container, Grid, Sidebar, SplitPanel, DashboardLayout	Layout components	primitives, design-tokens
theme/	Theme provider, CSS variable overrides per surface (learner, marketplace, employer, admin)	Theme context	design-tokens

packages/mock-data — Mock Data Layer

Component	Description	Boundaries	Depends On
competency-stacks.ts	5 competency stacks (AI Orchestration Engineer, AI Safety & Governance, Human-AI Product Designer, AI-Augmented Field Operator, Computational Sciences), each with 12-18 competencies	Typed mock data	packages/types
jobs.ts	20+ mock AI-era job listings with skills, seniority, salary, match scores	Typed mock data	packages/types
candidates.ts	15+ mock candidate profiles with artifacts, process traces, defense scores, microcredentials	Typed mock data	packages/types
employers.ts	10+ mock employer profiles with logos, descriptions, open positions	Typed mock data	packages/types
learner-progress.ts	Mock learner progress data: active competencies, completion percentages, recent artifacts	Typed mock data	packages/types
ai-tutor-responses.ts	Pre-scripted AI tutor chat responses for Coach and Tutor agent mockups	Typed mock data	packages/types

packages/types — Shared Types

Component	Description	Boundaries	Depends On
domain.ts	Competency, CompetencyStack, Microcredential, Artifact, ProcessTrace, OralDefense, AssessmentRubric	Domain types	None
marketplace.ts	Job, Employer, Candidate, JobPosting, TalentMatch, SearchFilter	Marketplace types	None
user.ts	Learner, Admin, EmployerUser, AgeGroup, Role	User types	None
ui.ts	Component props, theme config, breakpoint definitions	UI types	None

---

Data Flow

[Mock Data Layer] ──typed──> [Shared Types] <──typed──> [UI Components]
        │                                                    │
        │                                                    │
        ▼                                                    ▼
[Next.js Route Groups]                               [Surface Components]
  (learner)/         (marketplace)/     (employer)/      (admin)/
        │                  │                 │               │
        └──────────────────┴─────────────────┴───────────────┘
                                   │
                                   ▼
                          [Root Layout + Theme Provider]
                                   │
                                   ▼
                          [Responsive Navigation Shell]

All data flows from the mock data layer through typed imports into Next.js route handlers / server components, which pass data as props to UI components. No client-side data fetching, no API routes, no server actions in v0.1.

---

Build Order

1. Monorepo scaffolding — pnpm-workspace.yaml, turbo.json, tsconfig.json, package.json, Next.js app initialization
2. Shared types — packages/types with all domain, marketplace, user, and UI type definitions
3. Mock data layer — packages/mock-data with typed mock data for all surfaces
4. Design tokens — packages/ui/design-tokens with CSS custom properties
5. UI primitives — Button, Input, Card, Badge, Avatar, Dialog, Tabs, Progress, Tooltip, Skeleton, Toast
6. Root layout + navigation shell — Root layout with theme provider, responsive navigation, role switcher
7. UI composites — Navigation, Table, SearchBar, FilterPanel, ChatInterface, GraphViewer, ArtifactCard, CompetencyBadge, JobCard, CandidateCard, MetricCard
8. Learner surface routes — Landing, catalog, competency stack, dashboard, byte viewer, sandbox mockup, assessment mockup
9. Marketplace surface routes — Job board, job detail, employer profile, search/filter, pricing
10. Employer dashboard routes — Overview, talent search, candidate profile, posting management
11. Admin surface routes — Overview, learner management, competency graph viewer, moderation
12. Polish + integration — Cross-surface navigation, responsive QA, visual consistency, Storybook

---

Future Architecture (Post-v0.1, for reference)

The v0.1 prototype is designed to be replaced piece-by-piece with real backend services:

• Mock data → PostgreSQL + Drizzle ORM — mock data files replaced with database queries via repository layer
• Static routes → Fastify API + Next.js SSR — API routes replaced with Fastify backend services
• Mock AI tutor → Python FastAPI AI services — Chat interface mockup replaced with real AI agent microservices
• Mock assessment → Assessment engine — Assessment mockup replaced with process-trace grading + oral defense engine
• No auth → Identity verification + age-gating — Registration flow mockup replaced with real KYC and age verification
• No search → Semantic vector search (pgvector) — Filter UI replaced with vector similarity search
• No payments → Payment processing — Pricing page replaced with real subscription/payment flows

The monorepo structure (apps/web + packages/*) is designed to accommodate additional apps (e.g., apps/api, apps/ai-service) in future milestones without restructuring.