# ojus4/solvo-claude-platform architecture

> Architecture diagram of the GitHub repository ojus4/solvo-claude-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ojus4/solvo-claude-platform
- Repository: https://github.com/ojus4/solvo-claude-platform

## Overview

This repository is a single Next.js application that combines public marketing pages, authenticated user flows, an admin area, and a set of server-side API routes. The overall architecture is a monolith deployed on Vercel, with Supabase used as the backend data/auth layer and static JSON files used for some read-only domain data.

#### High-level shape

The app is organized around three user-facing zones:

1. **Public and auth entry points**
   - Landing page at `app/page.tsx`
   - Login/signup/access pages under `app/(auth)/...`
   - Auth error and suspended states under `app/auth/auth-error` and `app/suspended`

2. **Authenticated dashboard**
   - Dashboard page under `app/(dashboard)/dashboard/page.tsx`
   - Dashboard data fetched through `app/api/dashboard/data/route.ts`

3. **Admin and operational endpoints**
   - Admin promotions page under `app/admin/promotions/page.tsx`
   - Admin-only backend route `app/api/admin/applications/route.ts`
   - Supporting payment, assessment, psychometric, roadmap, PDF, and waitlist APIs

This is not a pure frontend app; the architecture is a mixed client/server React app with a substantial backend surface in Next.js route handlers.

#### Core technology boundaries

##### Frontend runtime
- **Next.js App Router** drives page routing and server/client composition.
- **React components** are split across route groups and shared component/provider utilities.
- **Tailwind/PostCSS/global CSS** provide the styling layer.
- `components/providers.tsx` suggests app-wide context providers are centralized there.

##### Backend runtime
- **Next.js route handlers** under `app/api/**/route.ts` are the main backend interface.
- The app uses **server-side Supabase clients** for secure data access and auth/session handling.
- There is a dedicated **Supabase admin client** for elevated operations, separated from regular user-scoped clients.

##### Data and integration layer
- **Supabase** is the main external system for identity and app data.
  - `lib/supabase/client.ts` for browser-side access
  - `lib/supabase/server.ts` for server-side requests
  - `lib/supabase/middleware-client.ts` for middleware/session bridging
  - `lib/supabase/admin-client.ts` for privileged operations
- **Email delivery** is abstracted in `lib/email/send.ts`.
- **PDF generation** is exposed through an API route, implying server-side document creation.
- **Static domain datasets** live in `public/data/` and are part of the application’s read model:
  - `job_trends.json`
  - `skills.json`
  - career roadmaps under `public/data/roadmaps/*.json`

#### Main subsystems

##### 1. Authentication and session control
Auth is handled through a combination of route pages, callback endpoints, Supabase clients, and middleware.

Key pieces:
- Login and signup pages in `app/(auth)/login` and `app/(auth)/signup`
- Access/invitation page in `app/(auth)/access/[slug]`
- Auth callback route(s) in:
  - `app/(auth)/auth/callback/route.ts`
  - `app/api/auth/callback/route.ts`
- Sign-out route in `app/api/auth/signout/route.ts`
- Middleware in `middleware.ts`

The middleware likely enforces:
- authenticated access to dashboard/admin areas
- session refresh or token propagation
- redirect handling for suspended/unauthorized users

The presence of `app/suspended/page.tsx` suggests there is an account status gate beyond basic login, likely based on user metadata or application state.

##### 2. User dashboard
The dashboard is a protected user area with its own data endpoint.

Flow:
- User lands on `app/(dashboard)/dashboard/page.tsx`
- Page fetches consolidated data from `app/api/dashboard/data/route.ts`
- The route likely aggregates account/profile, assessment, roadmap, payment, or application status from Supabase and returns a dashboard-ready shape

This separation indicates the UI is not directly querying many backend sources itself; instead, the dashboard consumes a single backend composition endpoint.

##### 3. Assessment and psychometric flows
There are two adjacent but distinct feature areas:

- `app/api/assessment/complete/route.ts`
- `app/api/psychometric/submit/route.ts`
- `app/api/psychometric/results/route.ts`

This suggests the product collects assessment inputs, stores them server-side, and later exposes computed results. The distinction between “assessment” and “psychometric” implies:
- one flow may finalize completion state
- the other may handle questionnaire responses and derived results

These routes likely write to Supabase and return derived scoring or eligibility data used elsewhere in the app.

##### 4. Roadmap/content delivery
Career roadmap content is modeled as route-driven dynamic lookup plus static JSON backing data.

Key pieces:
- `app/api/roadmap/[career]/route.ts`
- static files in `public/data/roadmaps/`

This is a strong architectural boundary: roadmap content appears to be delivered from versioned static data rather than a database-heavy CMS. The API route likely normalizes and serves roadmap data for a given career key, using the public JSON assets as the source of truth.

##### 5. Payments and entitlement flow
Payment is a first-class subsystem with multiple steps exposed as separate API routes:

- `app/api/payments/create-order/route.ts`
- `app/api/payments/verify/route.ts`
- `app/api/payments/webhook/route.ts`
- `app/api/payments/apply/route.ts`

This indicates a multi-stage payment lifecycle:
1. create an order
2. verify client-side or provider-side confirmation
3. accept asynchronous webhook events
4. apply the payment outcome to the user/account state

Because there is both verification and webhook handling, the payment system is designed to treat synchronous client confirmation and asynchronous provider callbacks as separate trust boundaries. The `apply` route likely turns a successful payment into a product entitlement, promotion, or access change.

##### 6. Admin operations
Admin functionality is separated into both UI and privileged backend access.

UI:
- `app/admin/promotions/page.tsx`

Backend:
- `app/api/admin/applications/route.ts`

Supporting authorization:
- `lib/admin/permissions.ts`

This suggests admin access is role-based and enforced in server code, not just by hiding the UI. The permissions helper likely centralizes checks against Supabase user metadata or application-specific role fields. The admin application route probably uses the privileged Supabase admin client to inspect or update sensitive records.

##### 7. Waitlist and lead capture
There is a dedicated waitlist endpoint:
- `app/api/waitlist/join/route.ts`

This is likely a low-friction public write path for collecting prospective users before full account activation or access approval. It may feed into email notifications or admin review.

##### 8. Document generation
The app includes:
- `app/api/pdf/generate/route.ts`

This indicates server-side generation of downloadable documents, likely tied to assessments, reports, or application summaries. Since it is a route handler, the PDF output is produced on demand rather than stored permanently in the client.

##### 9. Shared client-side state and hooks
There is a small but important client abstraction layer in `lib/`:
- `lib/hooks/useUser.ts`
- `lib/hooks/useSiteConfig.ts`
- `lib/store/userStore.ts`

These indicate the UI uses shared client state for user/session data and site configuration. The presence of a user store suggests the app avoids repeatedly fetching identity state in individual components and instead centralizes it in a client-side store.

##### 10. Utilities and notifications
- `lib/email/send.ts` handles outbound email
- `lib/utils.ts` is a general utility layer
- `types/index.ts` provides shared type definitions across frontend and backend boundaries

#### Important request/data flows

##### Auth flow
1. User hits login/signup/access pages.
2. Supabase authentication completes through callback handling.
3. Callback route writes/refreshes session state.
4. Middleware and server routes use Supabase server/middleware clients to enforce access.
5. Unauthorized or blocked users are redirected to auth error or suspended states.

##### Dashboard flow
1. Authenticated user opens the dashboard.
2. Dashboard page calls the dashboard data API.
3. API aggregates user data from Supabase and any derived state from assessment/payment/roadmap records.
4. Page renders a single composed view.

##### Assessment/psychometric flow
1. User submits questionnaire or assessment data.
2. Route handler validates and stores submissions.
3. A results endpoint returns calculated outputs.
4. Those results likely feed dashboard display, PDF generation, or application eligibility.

##### Payment flow
1. Client requests an order.
2. Payment provider confirmation is verified.
3. Webhook updates authoritative payment state.
4. Apply route converts payment state into access/entitlement changes.
5. Dashboard/admin surfaces the resulting status.

##### Roadmap/content flow
1. Client requests a career roadmap by slug.
2. Dynamic route loads the relevant roadmap definition.
3. Static JSON under `public/data/roadmaps` provides the canonical content.
4. UI renders the roadmap without needing a database write path.

##### Admin flow
1. Admin lands on promotions page.
2. Server-side permission checks determine access.
3. Admin route uses the Supabase admin client for elevated reads/writes.
4. Sensitive application changes are applied through server-only code.

#### Architectural boundaries to capture in a diagram

If you are drawing this repository, the most important boundaries are:

- **Browser/UI boundary**
  - pages, route groups, client hooks, provider/store layer

- **Next.js server boundary**
  - route handlers, server components, middleware, auth callbacks

- **Supabase boundary**
  - standard user client vs server client vs middleware client vs admin client

- **External integration boundary**
  - payment provider via create/verify/webhook
  - email delivery via `lib/email/send.ts`
  - PDF generation as a server-side output path

- **Static content boundary**
  - career roadmaps, job trends, and skill datasets in `public/data`

#### Repository-level interpretation

This repo is best understood as a product platform for career or assessment-driven access management:
- public users sign up or join a waitlist
- authenticated users view a dashboard and assessment/roadmap content
- payments unlock or apply access
- admins manage applications/promotions
- Supabase stores identity and application state
- Next.js route handlers provide the server orchestration layer

In short: a Next.js/Supabase application with clear separation between public acquisition, authenticated user experience, admin operations, and server-side orchestration for payments, assessments, documents, and content delivery.

Main entry points: [`solvo-platform/lib/supabase`](https://github.com/ojus4/solvo-claude-platform/tree/HEAD/solvo-platform/lib/supabase) (Supabase clients), [`solvo-platform/app/layout.tsx`](https://github.com/ojus4/solvo-claude-platform/blob/HEAD/solvo-platform/app/layout.tsx) (App shell), [`solvo-platform/components/providers.tsx`](https://github.com/ojus4/solvo-claude-platform/blob/HEAD/solvo-platform/components/providers.tsx) (Providers), [`solvo-platform/app/api/admin/applications/route.ts`](https://github.com/ojus4/solvo-claude-platform/blob/HEAD/solvo-platform/app/api/admin/applications/route.ts) (Admin API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Frontend"
  app_layout["App shell<br/>nextjs layout<br/>[layout.tsx]"]
  home_page["Landing<br/>marketing page<br/>[page.tsx]"]
  auth_pages["Auth pages<br/>route group"]
  dashboard_page["Dashboard<br/>protected page<br/>[page.tsx]"]
  admin_page["Admin promo<br/>admin page<br/>[page.tsx]"]
  providers["Providers<br/>react context<br/>[providers.tsx]"]
  user_hook["User hook<br/>client hook<br/>[useUser.ts]"]
  site_hook["Site config<br/>client hook<br/>[useSiteConfig.ts]"]
  user_store["User store<br/>client store<br/>[userStore.ts]"]
end

subgraph "Backend"
  middleware["Middleware<br/>request gate<br/>[middleware.ts]"]
  auth_routes["Auth routes<br/>api routes"]
  dashboard_api["Dashboard API<br/>composition route<br/>[route.ts]"]
  admin_api["Admin API<br/>privileged route<br/>[route.ts]"]
  assessment_api["Assessment API<br/>submission route<br/>[route.ts]"]
  psychometric_api["Psychometric API<br/>scoring routes"]
  payments_api["Payments API<br/>payment pipeline"]
  roadmap_api["Roadmap API<br/>content route<br/>[route.ts]"]
  waitlist_api["Waitlist API<br/>lead capture<br/>[route.ts]"]
  pdf_api["PDF API<br/>document route<br/>[route.ts]"]
end

subgraph "Data & Integrations"
  supabase_clients["Supabase clients<br/>data access"]
  admin_perms["Permissions<br/>rbac helper<br/>[permissions.ts]"]
  email_send["Email send<br/>mailer<br/>[send.ts]"]
  static_data[("Static data<br/>json assets")]
  shared_types["Shared types<br/>type defs<br/>[index.ts]"]
end

app_layout -->|"wraps"| providers
app_layout -->|"hosts"| home_page
app_layout -->|"hosts"| auth_pages
app_layout -->|"hosts"| dashboard_page
app_layout -->|"hosts"| admin_page
providers -->|"composes"| user_store
providers -->|"supports"| user_hook
providers -->|"supports"| site_hook
middleware -->|"uses"| supabase_clients
auth_pages -->|"calls"| auth_routes
auth_routes -->|"authenticates"| supabase_clients
middleware -->|"guards"| auth_pages
dashboard_page -->|"loads"| dashboard_api
dashboard_api -->|"reads"| supabase_clients
admin_page -->|"administers"| admin_api
admin_api -->|"checks"| admin_perms
admin_api -->|"writes"| supabase_clients
assessment_api -->|"stores"| supabase_clients
psychometric_api -->|"stores"| supabase_clients
payments_api -->|"updates"| supabase_clients
payments_api -->|"notifies"| email_send
roadmap_api -->|"serves"| static_data
waitlist_api -->|"notifies"| email_send
pdf_api -->|"reads"| supabase_clients
dashboard_api -->|"shapes"| shared_types
admin_api -->|"shapes"| shared_types
psychometric_api -->|"shapes"| shared_types

click app_layout "https://github.com/ojus4/solvo-claude-platform/blob/main/solvo-platform/app/layout.tsx"
click home_page "https://github.com/ojus4/solvo-claude-platform/blob/main/solvo-platform/app/page.tsx"
click auth_pages "https://github.com/ojus4/solvo-claude-platform/tree/main/solvo-platform/app/(auth)"
click dashboard_page "https://github.com/ojus4/solvo-claude-platform/blob/main/solvo-platform/app/(dashboard)/dashboard/page.tsx"
click admin_page "https://github.com/ojus4/solvo-claude-platform/blob/main/solvo-platform/app/admin/promotions/page.tsx"
click providers "https://github.com/ojus4/solvo-claude-platform/blob/main/solvo-platform/components/providers.tsx"
click user_hook "https://github.com/ojus4/solvo-claude-platform/blob/main/solvo-platform/lib/hooks/useUser.ts"
click site_hook "https://github.com/ojus4/solvo-claude-platform/blob/main/solvo-platform/lib/hooks/useSiteConfig.ts"
click user_store "https://github.com/ojus4/solvo-claude-platform/blob/main/solvo-platform/lib/store/userStore.ts"
click middleware "https://github.com/ojus4/solvo-claude-platform/blob/main/solvo-platform/middleware.ts"
click auth_routes "https://github.com/ojus4/solvo-claude-platform/tree/main/solvo-platform/app/api/auth"
click dashboard_api "https://github.com/ojus4/solvo-claude-platform/blob/main/solvo-platform/app/api/dashboard/data/route.ts"
click admin_api "https://github.com/ojus4/solvo-claude-platform/blob/main/solvo-platform/app/api/admin/applications/route.ts"
click assessment_api "https://github.com/ojus4/solvo-claude-platform/blob/main/solvo-platform/app/api/assessment/complete/route.ts"
click psychometric_api "https://github.com/ojus4/solvo-claude-platform/tree/main/solvo-platform/app/api/psychometric"
click payments_api "https://github.com/ojus4/solvo-claude-platform/tree/main/solvo-platform/app/api/payments"
click roadmap_api "https://github.com/ojus4/solvo-claude-platform/blob/main/solvo-platform/app/api/roadmap/[career]/route.ts"
click waitlist_api "https://github.com/ojus4/solvo-claude-platform/blob/main/solvo-platform/app/api/waitlist/join/route.ts"
click pdf_api "https://github.com/ojus4/solvo-claude-platform/blob/main/solvo-platform/app/api/pdf/generate/route.ts"
click supabase_clients "https://github.com/ojus4/solvo-claude-platform/tree/main/solvo-platform/lib/supabase"
click admin_perms "https://github.com/ojus4/solvo-claude-platform/blob/main/solvo-platform/lib/admin/permissions.ts"
click email_send "https://github.com/ojus4/solvo-claude-platform/blob/main/solvo-platform/lib/email/send.ts"
click static_data "https://github.com/ojus4/solvo-claude-platform/tree/main/solvo-platform/public/data"
click shared_types "https://github.com/ojus4/solvo-claude-platform/blob/main/solvo-platform/types/index.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 app_layout,home_page,auth_pages,dashboard_page,admin_page,providers,user_hook,site_hook,user_store toneBlue
class middleware,auth_routes,dashboard_api,admin_api,assessment_api,psychometric_api,payments_api,roadmap_api,waitlist_api,pdf_api toneAmber
class supabase_clients,admin_perms,email_send,static_data,shared_types toneMint
```

## Components

### Frontend

App Router pages, shared UI, and client state

- [App shell](https://github.com/ojus4/solvo-claude-platform/blob/HEAD/solvo-platform/app/layout.tsx): nextjs layout · Root layout and global styling for the app · `solvo-platform/app/layout.tsx`
- [Landing](https://github.com/ojus4/solvo-claude-platform/blob/HEAD/solvo-platform/app/page.tsx): marketing page · Public entry page · `solvo-platform/app/page.tsx`
- [Auth pages](https://github.com/ojus4/solvo-claude-platform/tree/HEAD/solvo-platform/app/(auth)): route group · Login, signup, access, auth error, and suspended views · `solvo-platform/app/(auth)`
- [Dashboard](https://github.com/ojus4/solvo-claude-platform/blob/HEAD/solvo-platform/app/(dashboard)/dashboard/page.tsx): protected page · Authenticated user dashboard view · `solvo-platform/app/(dashboard)/dashboard/page.tsx`
- [Admin promo](https://github.com/ojus4/solvo-claude-platform/blob/HEAD/solvo-platform/app/admin/promotions/page.tsx): admin page · Admin promotions interface · `solvo-platform/app/admin/promotions/page.tsx`
- [Providers](https://github.com/ojus4/solvo-claude-platform/blob/HEAD/solvo-platform/components/providers.tsx): react context · App-wide provider composition · `solvo-platform/components/providers.tsx`
- [User hook](https://github.com/ojus4/solvo-claude-platform/blob/HEAD/solvo-platform/lib/hooks/useUser.ts): client hook · Client-side user/session access · `solvo-platform/lib/hooks/useUser.ts`
- [Site config](https://github.com/ojus4/solvo-claude-platform/blob/HEAD/solvo-platform/lib/hooks/useSiteConfig.ts): client hook · Client-side site configuration access · `solvo-platform/lib/hooks/useSiteConfig.ts`
- [User store](https://github.com/ojus4/solvo-claude-platform/blob/HEAD/solvo-platform/lib/store/userStore.ts): client store · Shared user state container · `solvo-platform/lib/store/userStore.ts`

### Backend

Route handlers, middleware, and server-side orchestration

- [Middleware](https://github.com/ojus4/solvo-claude-platform/blob/HEAD/solvo-platform/middleware.ts): request gate · Session and access control at the edge · `solvo-platform/middleware.ts`
- [Auth routes](https://github.com/ojus4/solvo-claude-platform/tree/HEAD/solvo-platform/app/api/auth): api routes · Auth callback and sign-out handlers · `solvo-platform/app/api/auth`
- [Dashboard API](https://github.com/ojus4/solvo-claude-platform/blob/HEAD/solvo-platform/app/api/dashboard/data/route.ts): composition route · Aggregated dashboard data endpoint · `solvo-platform/app/api/dashboard/data/route.ts`
- [Admin API](https://github.com/ojus4/solvo-claude-platform/blob/HEAD/solvo-platform/app/api/admin/applications/route.ts): privileged route · Admin applications backend endpoint · `solvo-platform/app/api/admin/applications/route.ts`
- [Assessment API](https://github.com/ojus4/solvo-claude-platform/blob/HEAD/solvo-platform/app/api/assessment/complete/route.ts): submission route · Assessment completion endpoint · `solvo-platform/app/api/assessment/complete/route.ts`
- [Psychometric API](https://github.com/ojus4/solvo-claude-platform/tree/HEAD/solvo-platform/app/api/psychometric): scoring routes · Submit and results endpoints for psychometric flows · `solvo-platform/app/api/psychometric`
- [Payments API](https://github.com/ojus4/solvo-claude-platform/tree/HEAD/solvo-platform/app/api/payments): payment pipeline · Order creation, verification, webhook, and apply flow · `solvo-platform/app/api/payments`
- [Roadmap API](https://github.com/ojus4/solvo-claude-platform/blob/HEAD/solvo-platform/app/api/roadmap/%5Bcareer%5D/route.ts): content route · Career roadmap lookup endpoint · `solvo-platform/app/api/roadmap/[career]/route.ts`
- [Waitlist API](https://github.com/ojus4/solvo-claude-platform/blob/HEAD/solvo-platform/app/api/waitlist/join/route.ts): lead capture · Public waitlist join endpoint · `solvo-platform/app/api/waitlist/join/route.ts`
- [PDF API](https://github.com/ojus4/solvo-claude-platform/blob/HEAD/solvo-platform/app/api/pdf/generate/route.ts): document route · Server-side PDF generation endpoint · `solvo-platform/app/api/pdf/generate/route.ts`

### Data & Integrations

Supabase, static content, email, and generated outputs

- [Supabase clients](https://github.com/ojus4/solvo-claude-platform/tree/HEAD/solvo-platform/lib/supabase): data access · Browser, server, middleware, and admin Supabase clients · `solvo-platform/lib/supabase`
- [Permissions](https://github.com/ojus4/solvo-claude-platform/blob/HEAD/solvo-platform/lib/admin/permissions.ts): rbac helper · Admin authorization checks · `solvo-platform/lib/admin/permissions.ts`
- [Email send](https://github.com/ojus4/solvo-claude-platform/blob/HEAD/solvo-platform/lib/email/send.ts): mailer · Outbound email delivery helper · `solvo-platform/lib/email/send.ts`
- [Static data](https://github.com/ojus4/solvo-claude-platform/tree/HEAD/solvo-platform/public/data): json assets · Roadmaps, skills, and job trend datasets · `solvo-platform/public/data`
- [Shared types](https://github.com/ojus4/solvo-claude-platform/blob/HEAD/solvo-platform/types/index.ts): type defs · Cross-layer TypeScript contracts · `solvo-platform/types/index.ts`

## Connections

- App shell → Providers: wraps · Global providers compose inside the root shell
- App shell → Landing: hosts · Root route renders the landing page
- App shell → Auth pages: hosts · App Router route group for public auth pages
- App shell → Dashboard: hosts · Protected dashboard lives in the app shell
- App shell → Admin promo: hosts · Admin UI renders under the same shell
- Providers → User store: composes · Providers likely initialize shared user state
- Providers → User hook: supports · Hooks consume app-level context
- Providers → Site config: supports · Hooks consume app-level context
- Middleware → Supabase clients: uses · Middleware uses the session-aware Supabase client
- Auth pages → Auth routes: calls · Auth UI relies on callback and sign-out routes
- Auth routes → Supabase clients: authenticates · Auth handlers persist and refresh sessions
- Middleware → Auth pages: guards · Redirects or gates protected and suspended states
- Dashboard → Dashboard API: loads · Dashboard consumes one aggregated data endpoint
- Dashboard API → Supabase clients: reads · Backend data composition comes from Supabase
- Admin promo → Admin API: administers · Admin UI drives privileged application actions
- Admin API → Permissions: checks · Server-side role validation before sensitive actions
- Admin API → Supabase clients: writes · Privileged access uses the admin Supabase client
- Assessment API → Supabase clients: stores · Assessment completion persists server-side state
- Psychometric API → Supabase clients: stores · Submission and results use Supabase-backed state
- Payments API → Supabase clients: updates · Payment state is recorded and applied server-side
- Payments API → Email send: notifies · Payment lifecycle may trigger email delivery
- Roadmap API → Static data: serves · Career roadmaps are read from static JSON assets
- Waitlist API → Email send: notifies · Waitlist signup can trigger outbound email
- PDF API → Supabase clients: reads · PDF generation likely uses stored user or report data
- Dashboard API → Shared types: shapes · Shared contracts define response payloads
- Admin API → Shared types: shapes · Shared contracts define admin data shapes
- Psychometric API → Shared types: shapes · Shared contracts define scoring/result payloads
