# nurasss/t-skills.kz architecture

> Architecture diagram of the GitHub repository nurasss/t-skills.kz, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nurasss/t-skills.kz
- Repository: https://github.com/nurasss/t-skills.kz

## Overview

T-Skills is a closed-beta assessment product centered on a versioned assessment workflow: users enter through the web UI, submit responses through assessment APIs, and the server scores and persists sessions before presenting reports. Related branches cover teen assessments, accounts and privacy requests, checkout, and administration. Source excerpts show the controller, scoring, persistence, authentication, and validation layers; several other capabilities are documented in the README but their implementation details were not sampled, so those links are documented rather than inferred from module names.

Main entry points: [`lib/durable-store.ts`](https://github.com/nurasss/t-skills.kz/blob/main/lib/durable-store.ts) (Assessment and account store), [`app/orbita-app.tsx`](https://github.com/nurasss/t-skills.kz/blob/main/app/orbita-app.tsx) (Web shell and views), [`app/api/assessments/route.ts`](https://github.com/nurasss/t-skills.kz/blob/main/app/api/assessments/route.ts) (Assessment APIs), [`db/index.ts`](https://github.com/nurasss/t-skills.kz/blob/main/db/index.ts) (D1 and R2 bindings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["Web shell and views<br/>[orbita-app.tsx]"]
  node_controller["Workflow controller"]
  node_assessment_ui["Assessment views"]
end

subgraph group_assessment["Assessment domain"]
  node_assessment_api["Assessment APIs<br/>[route.ts]"]
  node_engine["Scoring engine"]
  node_item_bank["Assessment item bank<br/>[item-bank.ts]"]
  node_version_contract["Version contracts<br/>[versions.ts]"]
  node_v5_pipeline["Prepared v5 pipeline<br/>[pipeline.ts]"]
  node_teen_flow["Teen assessment flow<br/>[teen-flow-view.tsx]"]
  node_reports["Reports and PDFs<br/>[route.ts]"]
end

subgraph group_platform["Identity and data"]
  node_store[("Assessment and account store<br/>[durable-store.ts]")]
  node_d1_r2[("D1 and R2 bindings<br/>[index.ts]")]
  node_auth["Application identity<br/>[app-auth.ts]"]
  node_auth_api["Authentication APIs<br/>[route.ts]"]
  node_privacy_api["Export and deletion APIs<br/>[route.ts]"]
  node_retention["Scheduled retention<br/>[route.ts]"]
end

subgraph group_commerce["Commerce and operations"]
  node_checkout_api["Checkout API<br/>[route.ts]"]
  node_payments["Payment provider"]
  node_webhook["Payment webhooks<br/>[route.ts]"]
end

subgraph group_control["Administration"]
  node_admin_ui["Admin console<br/>[admin-console.tsx]"]
  node_admin_api["Admin APIs<br/>[route.ts]"]
  node_admin_store[("Admin store<br/>[admin-store.ts]")]
end

node_user(("Assessment user"))
node_d1_user[("D1 database")]
node_r2_bucket[("Private R2 artifacts")]
node_payment_service["Payment service"]

node_user -->|"uses"| node_web
node_web -->|"composes"| node_controller
node_controller -->|"submits responses"| node_assessment_api
node_web -->|"routes views"| node_assessment_ui
node_assessment_api -->|"creates sessions"| node_store
node_store -->|"scores responses"| node_engine
node_engine -->|"uses items"| node_item_bank
node_assessment_api -->|"selects contract"| node_version_contract
node_store -->|"uses bindings"| node_d1_r2
node_d1_r2 -->|"persists state"| node_d1_user
node_store -.->|"stores report artifacts"| node_reports
node_reports -.->|"serves private files"| node_r2_bucket
node_user -->|"registers"| node_auth_api
node_auth_api -->|"creates identity"| node_auth
node_auth -->|"uses D1"| node_d1_r2
node_user -->|"starts checkout"| node_checkout_api
node_checkout_api -->|"creates payment"| node_payments
node_payments -.->|"integrates"| node_payment_service
node_payment_service -.->|"sends events"| node_webhook
node_user -->|"requests export or deletion"| node_privacy_api
node_privacy_api -.->|"updates account data"| node_store
node_retention -->|"applies retention"| node_store
node_admin_ui -.->|"manages operations"| node_admin_api
node_admin_api -.->|"uses admin data"| node_admin_store
node_admin_ui -.->|"manages content and settings"| node_admin_api
node_user -.->|"takes teen assessment"| node_teen_flow
node_v5_pipeline -.->|"keeps versioned contract"| node_version_contract

click node_web "https://github.com/nurasss/t-skills.kz/blob/main/app/orbita-app.tsx"
click node_controller "https://github.com/nurasss/t-skills.kz/blob/main/hooks/use-orbita-controller.ts"
click node_assessment_api "https://github.com/nurasss/t-skills.kz/blob/main/app/api/assessments/route.ts"
click node_assessment_ui "https://github.com/nurasss/t-skills.kz/blob/main/app/views/assessment/assessment-view.tsx"
click node_engine "https://github.com/nurasss/t-skills.kz/blob/main/lib/assessment-engine.ts"
click node_item_bank "https://github.com/nurasss/t-skills.kz/blob/main/lib/item-bank.ts"
click node_version_contract "https://github.com/nurasss/t-skills.kz/blob/main/lib/t-skills/versions.ts"
click node_v5_pipeline "https://github.com/nurasss/t-skills.kz/blob/main/lib/t-skills/v5/pipeline.ts"
click node_teen_flow "https://github.com/nurasss/t-skills.kz/blob/main/app/views/teen/teen-flow-view.tsx"
click node_store "https://github.com/nurasss/t-skills.kz/blob/main/lib/durable-store.ts"
click node_d1_r2 "https://github.com/nurasss/t-skills.kz/blob/main/db/index.ts"
click node_auth "https://github.com/nurasss/t-skills.kz/blob/main/lib/app-auth.ts"
click node_auth_api "https://github.com/nurasss/t-skills.kz/blob/main/app/api/auth/register/route.ts"
click node_checkout_api "https://github.com/nurasss/t-skills.kz/blob/main/app/api/checkout/route.ts"
click node_payments "https://github.com/nurasss/t-skills.kz/blob/main/lib/payment-provider.ts"
click node_webhook "https://github.com/nurasss/t-skills.kz/blob/main/app/api/payments/webhook/route.ts"
click node_reports "https://github.com/nurasss/t-skills.kz/blob/main/app/api/reports/%5Bid%5D/download/route.ts"
click node_privacy_api "https://github.com/nurasss/t-skills.kz/blob/main/app/api/account/export/route.ts"
click node_retention "https://github.com/nurasss/t-skills.kz/blob/main/app/internal/retention/route.ts"
click node_admin_ui "https://github.com/nurasss/t-skills.kz/blob/main/app/admin/admin-console.tsx"
click node_admin_api "https://github.com/nurasss/t-skills.kz/blob/main/app/api/admin/overview/route.ts"
click node_admin_store "https://github.com/nurasss/t-skills.kz/blob/main/lib/admin-store.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_web,node_controller,node_assessment_ui,node_user toneBlue
class node_assessment_api,node_engine,node_item_bank,node_version_contract,node_v5_pipeline,node_teen_flow,node_reports,node_d1_user,node_r2_bucket toneAmber
class node_store,node_d1_r2,node_auth,node_auth_api,node_privacy_api,node_retention toneMint
class node_checkout_api,node_payments,node_webhook toneRose
class node_admin_ui,node_admin_api,node_admin_store,node_payment_service toneIndigo
```

## Components

### User experience

- [Web shell and views](https://github.com/nurasss/t-skills.kz/blob/main/app/orbita-app.tsx): `app/orbita-app.tsx`
- [Workflow controller](https://github.com/nurasss/t-skills.kz/blob/main/hooks/use-orbita-controller.ts): `hooks/use-orbita-controller.ts`
- [Assessment views](https://github.com/nurasss/t-skills.kz/blob/main/app/views/assessment/assessment-view.tsx): `app/views/assessment/assessment-view.tsx`

### Assessment domain

- [Assessment APIs](https://github.com/nurasss/t-skills.kz/blob/main/app/api/assessments/route.ts): `app/api/assessments/route.ts`
- [Scoring engine](https://github.com/nurasss/t-skills.kz/blob/main/lib/assessment-engine.ts): `lib/assessment-engine.ts`
- [Assessment item bank](https://github.com/nurasss/t-skills.kz/blob/main/lib/item-bank.ts): `lib/item-bank.ts`
- [Version contracts](https://github.com/nurasss/t-skills.kz/blob/main/lib/t-skills/versions.ts): `lib/t-skills/versions.ts`
- [Prepared v5 pipeline](https://github.com/nurasss/t-skills.kz/blob/main/lib/t-skills/v5/pipeline.ts): `lib/t-skills/v5/pipeline.ts`
- [Teen assessment flow](https://github.com/nurasss/t-skills.kz/blob/main/app/views/teen/teen-flow-view.tsx): `app/views/teen/teen-flow-view.tsx`
- [Reports and PDFs](https://github.com/nurasss/t-skills.kz/blob/main/app/api/reports/%5Bid%5D/download/route.ts): `app/api/reports/[id]/download/route.ts`

### Identity and data

- [Assessment and account store](https://github.com/nurasss/t-skills.kz/blob/main/lib/durable-store.ts): `lib/durable-store.ts`
- [D1 and R2 bindings](https://github.com/nurasss/t-skills.kz/blob/main/db/index.ts): `db/index.ts`
- [Application identity](https://github.com/nurasss/t-skills.kz/blob/main/lib/app-auth.ts): `lib/app-auth.ts`
- [Authentication APIs](https://github.com/nurasss/t-skills.kz/blob/main/app/api/auth/register/route.ts): `app/api/auth/register/route.ts`
- [Export and deletion APIs](https://github.com/nurasss/t-skills.kz/blob/main/app/api/account/export/route.ts): `app/api/account/export/route.ts`
- [Scheduled retention](https://github.com/nurasss/t-skills.kz/blob/main/app/internal/retention/route.ts): `app/internal/retention/route.ts`

### Commerce and operations

- [Checkout API](https://github.com/nurasss/t-skills.kz/blob/main/app/api/checkout/route.ts): `app/api/checkout/route.ts`
- [Payment provider](https://github.com/nurasss/t-skills.kz/blob/main/lib/payment-provider.ts): `lib/payment-provider.ts`
- [Payment webhooks](https://github.com/nurasss/t-skills.kz/blob/main/app/api/payments/webhook/route.ts): `app/api/payments/webhook/route.ts`

### Administration

- [Admin console](https://github.com/nurasss/t-skills.kz/blob/main/app/admin/admin-console.tsx): `app/admin/admin-console.tsx`
- [Admin APIs](https://github.com/nurasss/t-skills.kz/blob/main/app/api/admin/overview/route.ts): `app/api/admin/overview/route.ts`
- [Admin store](https://github.com/nurasss/t-skills.kz/blob/main/lib/admin-store.ts): `lib/admin-store.ts`

### Other components

- **Assessment user**
- **D1 database**
- **Private R2 artifacts**
- **Payment service**

## Connections

- Assessment user → Web shell and views: uses (evidence: `README.md`)
- Web shell and views → Workflow controller: composes (evidence: `app/orbita-app.tsx`)
- Workflow controller → Assessment APIs: submits responses (evidence: `hooks/use-orbita-controller.ts`)
- Web shell and views → Assessment views: routes views
- Assessment APIs → Assessment and account store: creates sessions (evidence: `app/api/assessments/route.ts`)
- Assessment and account store → Scoring engine: scores responses (evidence: `lib/durable-store.ts`)
- Scoring engine → Assessment item bank: uses items (evidence: `lib/assessment-engine.ts`)
- Assessment APIs → Version contracts: selects contract (evidence: `app/api/assessments/route.ts`)
- Assessment and account store → D1 and R2 bindings: uses bindings (evidence: `lib/durable-store.ts`)
- D1 and R2 bindings → D1 database: persists state (evidence: `db/index.ts`)
- Assessment and account store → Reports and PDFs: stores report artifacts
- Reports and PDFs → Private R2 artifacts: serves private files (evidence: `README.md`)
- Assessment user → Authentication APIs: registers (evidence: `README.md`)
- Authentication APIs → Application identity: creates identity (evidence: `app/api/auth/register/route.ts`)
- Application identity → D1 and R2 bindings: uses D1 (evidence: `lib/app-auth.ts`)
- Assessment user → Checkout API: starts checkout (evidence: `README.md`)
- Checkout API → Payment provider: creates payment (evidence: `app/api/checkout/route.ts`)
- Payment provider → Payment service: integrates (evidence: `README.md`)
- Payment service → Payment webhooks: sends events (evidence: `README.md`)
- Assessment user → Export and deletion APIs: requests export or deletion (evidence: `README.md`)
- Export and deletion APIs → Assessment and account store: updates account data
- Scheduled retention → Assessment and account store: applies retention (evidence: `app/internal/retention/route.ts`)
- Admin console → Admin APIs: manages operations (evidence: `README.md`)
- Admin APIs → Admin store: uses admin data
- Admin console → Admin APIs: manages content and settings (evidence: `README.md`)
- Assessment user → Teen assessment flow: takes teen assessment (evidence: `README.md`)
- Prepared v5 pipeline → Version contracts: keeps versioned contract (evidence: `README.md`)