# alfintg/careerx architecture

> Architecture diagram of the GitHub repository alfintg/careerx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alfintg/careerx
- Repository: https://github.com/alfintg/careerx

## Overview

CareerX turns a student’s year, skills, and interests into three personalized career trajectories, then presents fit scores, skill gaps, milestones, projects, and a first-month plan. The main flow runs from the profile form through the simulation API and its AI-or-fallback generation paths to the results and detail views. The README documents this workflow; source excerpts show the API routing, AI processing, and frontend request, but not every UI interaction or runtime detail.

Main entry points: [`app/api/simulate/route.ts`](https://github.com/alfintg/careerx/blob/main/app/api/simulate/route.ts) (Simulation endpoint), [`lib/ai/simulate.ts`](https://github.com/alfintg/careerx/blob/main/lib/ai/simulate.ts) (AI simulation), [`lib/schema.ts`](https://github.com/alfintg/careerx/blob/main/lib/schema.ts) (Request and result schemas), [`app/page.tsx`](https://github.com/alfintg/careerx/blob/main/app/page.tsx) (Profile form)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Student experience"]
  node_profile["Profile form<br/>[page.tsx]"]
  node_results["Trajectory results<br/>[page.tsx]"]
  node_detail["Path details<br/>[page.tsx]"]
end

subgraph group_api["Simulation API"]
  node_route["Simulation endpoint<br/>[route.ts]"]
end

subgraph group_generation["Career generation"]
  node_ai["AI simulation<br/>[simulate.ts]"]
  node_prompts["Prompt builder<br/>[prompt.ts]"]
  node_normalizer["JSON normalizer<br/>[normalize.ts]"]
  node_fallback["Fallback results<br/>[result.ts]"]
  node_mock["Mock results<br/>[simulate.json]"]
end

subgraph group_contracts["Data contracts"]
  node_schema["Request and result schemas<br/>[schema.ts]"]
end

node_student(("Student"))
node_anthropic["Anthropic Claude"]

node_student -->|"enters profile"| node_profile
node_profile -->|"submits profile"| node_route
node_route -->|"validates request"| node_schema
node_route -->|"validates mock"| node_schema
node_route -->|"calls simulation"| node_ai
node_route -->|"reads mock data"| node_mock
node_route -->|"serves fallback"| node_fallback
node_ai -->|"builds prompts"| node_prompts
node_ai -->|"requests generation"| node_anthropic
node_ai -->|"parses output"| node_normalizer
node_ai -->|"validates result"| node_schema
node_ai -->|"returns fallback"| node_fallback
node_route -->|"returns paths"| node_results
node_results -.->|"opens selected path"| node_detail

click node_profile "https://github.com/alfintg/careerx/blob/main/app/page.tsx"
click node_results "https://github.com/alfintg/careerx/blob/main/app/page.tsx"
click node_detail "https://github.com/alfintg/careerx/blob/main/app/page.tsx"
click node_route "https://github.com/alfintg/careerx/blob/main/app/api/simulate/route.ts"
click node_ai "https://github.com/alfintg/careerx/blob/main/lib/ai/simulate.ts"
click node_prompts "https://github.com/alfintg/careerx/blob/main/lib/ai/prompt.ts"
click node_normalizer "https://github.com/alfintg/careerx/blob/main/lib/ai/normalize.ts"
click node_fallback "https://github.com/alfintg/careerx/blob/main/lib/fallback/result.ts"
click node_mock "https://github.com/alfintg/careerx/blob/main/lib/mock/simulate.json"
click node_schema "https://github.com/alfintg/careerx/blob/main/lib/schema.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_profile,node_results,node_detail toneBlue
class node_route toneAmber
class node_ai,node_prompts,node_normalizer,node_fallback,node_mock toneMint
class node_schema toneRose
class node_student,node_anthropic toneIndigo
```

## Components

### Student experience

- [Profile form](https://github.com/alfintg/careerx/blob/main/app/page.tsx): `app/page.tsx`
- [Trajectory results](https://github.com/alfintg/careerx/blob/main/app/page.tsx): `app/page.tsx`
- [Path details](https://github.com/alfintg/careerx/blob/main/app/page.tsx): `app/page.tsx`

### Simulation API

- [Simulation endpoint](https://github.com/alfintg/careerx/blob/main/app/api/simulate/route.ts): `app/api/simulate/route.ts`

### Career generation

- [AI simulation](https://github.com/alfintg/careerx/blob/main/lib/ai/simulate.ts): `lib/ai/simulate.ts`
- [Prompt builder](https://github.com/alfintg/careerx/blob/main/lib/ai/prompt.ts): `lib/ai/prompt.ts`
- [JSON normalizer](https://github.com/alfintg/careerx/blob/main/lib/ai/normalize.ts): `lib/ai/normalize.ts`
- [Fallback results](https://github.com/alfintg/careerx/blob/main/lib/fallback/result.ts): `lib/fallback/result.ts`
- [Mock results](https://github.com/alfintg/careerx/blob/main/lib/mock/simulate.json): `lib/mock/simulate.json`

### Data contracts

- [Request and result schemas](https://github.com/alfintg/careerx/blob/main/lib/schema.ts): `lib/schema.ts`

### Other components

- **Student**
- **Anthropic Claude**

## Connections

- Student → Profile form: enters profile (evidence: `README.md`)
- Profile form → Simulation endpoint: submits profile (evidence: `app/page.tsx`)
- Simulation endpoint → Request and result schemas: validates request (evidence: `app/api/simulate/route.ts`)
- Simulation endpoint → Request and result schemas: validates mock (evidence: `app/api/simulate/route.ts`)
- Simulation endpoint → AI simulation: calls simulation (evidence: `app/api/simulate/route.ts`)
- Simulation endpoint → Mock results: reads mock data (evidence: `app/api/simulate/route.ts`)
- Simulation endpoint → Fallback results: serves fallback (evidence: `app/api/simulate/route.ts`)
- AI simulation → Prompt builder: builds prompts (evidence: `lib/ai/simulate.ts`)
- AI simulation → Anthropic Claude: requests generation (evidence: `lib/ai/simulate.ts`)
- AI simulation → JSON normalizer: parses output (evidence: `lib/ai/simulate.ts`)
- AI simulation → Request and result schemas: validates result (evidence: `lib/ai/simulate.ts`)
- AI simulation → Fallback results: returns fallback (evidence: `lib/ai/simulate.ts`)
- Simulation endpoint → Trajectory results: returns paths (evidence: `README.md`)
- Trajectory results → Path details: opens selected path (evidence: `app/page.tsx`)
