# ragavendren/assessa architecture

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

- Interactive diagram: https://gitdiagram.com/ragavendren/assessa
- Repository: https://github.com/ragavendren/assessa

## Overview

Assessa is an online assessment and learning platform. Admins create question banks and assessments, control availability, and share links; participants authenticate or enter via public links, take server-scored assessments, and review progress. A separate play experience provides live Arena and Pulse activities alongside self-paced modes, leaderboards, and rewards. The graph also includes authentication/email, AI insights, and help capabilities documented in the README. Some feature modules were not sampled, so their connections are included only where README or indexed references support them.

Main entry points: [`src/routes/auth.tsx`](https://github.com/ragavendren/assessa/blob/main/src/routes/auth.tsx) (Sign-in & callback), [`src/lib/platform.functions.ts`](https://github.com/ragavendren/assessa/blob/main/src/lib/platform.functions.ts) (Assessment services), [`src/lib/play.functions.ts`](https://github.com/ragavendren/assessa/blob/main/src/lib/play.functions.ts) (Play operations), [`src/routes/_authenticated/route.tsx`](https://github.com/ragavendren/assessa/blob/main/src/routes/_authenticated/route.tsx) (Authenticated routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access &amp; profiles"]
  node_public_site["Public entry<br/>[index.tsx]"]
  node_auth_routes["Sign-in &amp; callback<br/>[auth.tsx]"]
  node_session["Client session<br/>[auth-session.ts]"]
  node_auth_gate["Authenticated routes<br/>[route.tsx]"]
  node_app_shell["App shell<br/>[AppShell.tsx]"]
  node_profile["Profile bootstrap"]
end

subgraph group_assessment["Assessment management"]
  node_exam_admin["Exam authoring<br/>[ExamEditor.tsx]"]
  node_pool_admin["Question pools &amp; blueprints"]
  node_admin_api["Admin operations<br/>[admin.functions.ts]"]
  node_assessment_api["Assessment services"]
  node_assessment_core["Scoring &amp; attempts<br/>[platform.server.ts]"]
end

subgraph group_play["Play &amp; rewards"]
  node_play_routes["Play experiences"]
  node_play_api["Play operations<br/>[play.functions.ts]"]
  node_play_server["Play session engine<br/>[play.server.ts]"]
  node_arena["Live Arena"]
  node_pulse["Pulse activities"]
  node_gamification["Progress &amp; rewards<br/>[gamification.ts]"]
end

subgraph group_platform["Platform services"]
  node_router["Route registry<br/>[routeTree.gen.ts]"]
  node_supabase_client["Supabase client<br/>[client.ts]"]
  node_auth_middleware["Server auth middleware<br/>[auth-middleware.ts]"]
  node_supabase_admin["Privileged database client<br/>[client.server.ts]"]
  node_database[("Supabase")]
  node_ai["Gemini / AI gateway"]
  node_ai_service["AI insights service"]
  node_mail_hook["Auth email hook"]
  node_email_service["Resend"]
  node_help["Help center &amp; bot<br/>[HelpCenter.tsx]"]
end

node_participant(("Participant / admin"))

node_participant -->|"visits"| node_public_site
node_public_site -->|"links to"| node_auth_routes
node_participant -->|"signs in"| node_auth_routes
node_auth_routes -->|"authenticates with"| node_supabase_client
node_auth_routes -->|"persists signup context"| node_session
node_auth_gate -->|"resolves session"| node_session
node_auth_gate -->|"renders"| node_app_shell
node_app_shell -->|"loads profile"| node_profile
node_profile -->|"requires auth"| node_auth_middleware
node_exam_admin -->|"uses admin operations"| node_admin_api
node_exam_admin -->|"uses platform services"| node_assessment_api
node_pool_admin -.->|"manages pools"| node_admin_api
node_participant -->|"starts activities"| node_play_routes
node_play_routes -->|"invokes"| node_play_api
node_play_api -->|"delegates to"| node_play_server
node_play_api -->|"dispatches Arena"| node_arena
node_play_api -.->|"dispatches Pulse"| node_pulse
node_play_server -.->|"uses reward logic"| node_gamification
node_router -->|"registers route"| node_auth_gate
node_auth_routes -->|"uses auth client"| node_supabase_client
node_assessment_api -->|"protects functions"| node_auth_middleware
node_assessment_api -->|"delegates assessment work"| node_assessment_core
node_assessment_api -->|"uses privileged access"| node_supabase_admin
node_assessment_core -.->|"reads and writes"| node_database
node_supabase_client -->|"connects to"| node_database
node_supabase_admin -->|"connects with service role"| node_database
node_auth_middleware -->|"validates user"| node_database
node_participant -->|"requests insights"| node_ai_service
node_ai_service -.->|"uses model provider"| node_ai
node_mail_hook -->|"sends auth email"| node_email_service
node_participant -->|"asks for help"| node_help

click node_public_site "https://github.com/ragavendren/assessa/blob/main/src/routes/index.tsx"
click node_auth_routes "https://github.com/ragavendren/assessa/blob/main/src/routes/auth.tsx"
click node_session "https://github.com/ragavendren/assessa/blob/main/src/lib/auth-session.ts"
click node_auth_gate "https://github.com/ragavendren/assessa/blob/main/src/routes/_authenticated/route.tsx"
click node_app_shell "https://github.com/ragavendren/assessa/blob/main/src/components/AppShell.tsx"
click node_profile "https://github.com/ragavendren/assessa/blob/main/src/lib/platform.functions.ts"
click node_exam_admin "https://github.com/ragavendren/assessa/blob/main/src/components/admin/ExamEditor.tsx"
click node_pool_admin "https://github.com/ragavendren/assessa/blob/main/src/routes/_authenticated/admin.pools.index.tsx"
click node_admin_api "https://github.com/ragavendren/assessa/blob/main/src/lib/admin.functions.ts"
click node_assessment_api "https://github.com/ragavendren/assessa/blob/main/src/lib/platform.functions.ts"
click node_assessment_core "https://github.com/ragavendren/assessa/blob/main/src/lib/platform.server.ts"
click node_play_routes "https://github.com/ragavendren/assessa/blob/main/src/routes/_authenticated/play.session.%24sessionId.tsx"
click node_play_api "https://github.com/ragavendren/assessa/blob/main/src/lib/play.functions.ts"
click node_play_server "https://github.com/ragavendren/assessa/blob/main/src/lib/play.server.ts"
click node_arena "https://github.com/ragavendren/assessa/blob/main/src/lib/play.arena.server.ts"
click node_pulse "https://github.com/ragavendren/assessa/blob/main/src/lib/play.pulse.server.ts"
click node_gamification "https://github.com/ragavendren/assessa/blob/main/src/lib/gamification.ts"
click node_router "https://github.com/ragavendren/assessa/blob/main/src/routeTree.gen.ts"
click node_supabase_client "https://github.com/ragavendren/assessa/blob/main/src/integrations/supabase/client.ts"
click node_auth_middleware "https://github.com/ragavendren/assessa/blob/main/src/integrations/supabase/auth-middleware.ts"
click node_supabase_admin "https://github.com/ragavendren/assessa/blob/main/src/integrations/supabase/client.server.ts"
click node_ai_service "https://github.com/ragavendren/assessa/blob/main/src/lib/ai-gateway.server.ts"
click node_mail_hook "https://github.com/ragavendren/assessa/blob/main/src/lib/auth-email-hook.server.ts"
click node_help "https://github.com/ragavendren/assessa/blob/main/src/components/help/HelpCenter.tsx"

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_public_site,node_auth_routes,node_session,node_auth_gate,node_app_shell,node_profile toneBlue
class node_exam_admin,node_pool_admin,node_admin_api,node_assessment_api,node_assessment_core toneAmber
class node_play_routes,node_play_api,node_play_server,node_arena,node_pulse,node_gamification toneMint
class node_router,node_supabase_client,node_auth_middleware,node_supabase_admin,node_database,node_ai,node_ai_service,node_mail_hook,node_email_service,node_help toneRose
class node_participant toneIndigo
```

## Components

### Access & profiles

- [Public entry](https://github.com/ragavendren/assessa/blob/main/src/routes/index.tsx): `src/routes/index.tsx`
- [Sign-in & callback](https://github.com/ragavendren/assessa/blob/main/src/routes/auth.tsx): `src/routes/auth.tsx`
- [Client session](https://github.com/ragavendren/assessa/blob/main/src/lib/auth-session.ts): `src/lib/auth-session.ts`
- [Authenticated routes](https://github.com/ragavendren/assessa/blob/main/src/routes/_authenticated/route.tsx): `src/routes/_authenticated/route.tsx`
- [App shell](https://github.com/ragavendren/assessa/blob/main/src/components/AppShell.tsx): `src/components/AppShell.tsx`
- [Profile bootstrap](https://github.com/ragavendren/assessa/blob/main/src/lib/platform.functions.ts): `src/lib/platform.functions.ts`

### Assessment management

- [Exam authoring](https://github.com/ragavendren/assessa/blob/main/src/components/admin/ExamEditor.tsx): `src/components/admin/ExamEditor.tsx`
- [Question pools & blueprints](https://github.com/ragavendren/assessa/blob/main/src/routes/_authenticated/admin.pools.index.tsx): `src/routes/_authenticated/admin.pools.index.tsx`
- [Admin operations](https://github.com/ragavendren/assessa/blob/main/src/lib/admin.functions.ts): `src/lib/admin.functions.ts`
- [Assessment services](https://github.com/ragavendren/assessa/blob/main/src/lib/platform.functions.ts): `src/lib/platform.functions.ts`
- [Scoring & attempts](https://github.com/ragavendren/assessa/blob/main/src/lib/platform.server.ts): `src/lib/platform.server.ts`

### Play & rewards

- [Play experiences](https://github.com/ragavendren/assessa/blob/main/src/routes/_authenticated/play.session.%24sessionId.tsx): `src/routes/_authenticated/play.session.$sessionId.tsx`
- [Play operations](https://github.com/ragavendren/assessa/blob/main/src/lib/play.functions.ts): `src/lib/play.functions.ts`
- [Play session engine](https://github.com/ragavendren/assessa/blob/main/src/lib/play.server.ts): `src/lib/play.server.ts`
- [Live Arena](https://github.com/ragavendren/assessa/blob/main/src/lib/play.arena.server.ts): `src/lib/play.arena.server.ts`
- [Pulse activities](https://github.com/ragavendren/assessa/blob/main/src/lib/play.pulse.server.ts): `src/lib/play.pulse.server.ts`
- [Progress & rewards](https://github.com/ragavendren/assessa/blob/main/src/lib/gamification.ts): `src/lib/gamification.ts`

### Platform services

- [Route registry](https://github.com/ragavendren/assessa/blob/main/src/routeTree.gen.ts): `src/routeTree.gen.ts`
- [Supabase client](https://github.com/ragavendren/assessa/blob/main/src/integrations/supabase/client.ts): `src/integrations/supabase/client.ts`
- [Server auth middleware](https://github.com/ragavendren/assessa/blob/main/src/integrations/supabase/auth-middleware.ts): `src/integrations/supabase/auth-middleware.ts`
- [Privileged database client](https://github.com/ragavendren/assessa/blob/main/src/integrations/supabase/client.server.ts): `src/integrations/supabase/client.server.ts`
- **Supabase**
- **Gemini / AI gateway**
- [AI insights service](https://github.com/ragavendren/assessa/blob/main/src/lib/ai-gateway.server.ts): `src/lib/ai-gateway.server.ts`
- [Auth email hook](https://github.com/ragavendren/assessa/blob/main/src/lib/auth-email-hook.server.ts): `src/lib/auth-email-hook.server.ts`
- **Resend**
- [Help center & bot](https://github.com/ragavendren/assessa/blob/main/src/components/help/HelpCenter.tsx): `src/components/help/HelpCenter.tsx`

### Other components

- **Participant / admin**

## Connections

- Participant / admin → Public entry: visits (evidence: `src/routes/index.tsx`)
- Public entry → Sign-in & callback: links to (evidence: `src/routes/index.tsx`)
- Participant / admin → Sign-in & callback: signs in (evidence: `README.md`)
- Sign-in & callback → Supabase client: authenticates with (evidence: `src/routes/auth.tsx`)
- Sign-in & callback → Client session: persists signup context (evidence: `src/routes/auth.tsx`)
- Authenticated routes → Client session: resolves session (evidence: `src/routes/_authenticated/route.tsx`)
- Authenticated routes → App shell: renders (evidence: `src/routes/_authenticated/route.tsx`)
- App shell → Profile bootstrap: loads profile (evidence: `src/components/AppShell.tsx`)
- Profile bootstrap → Server auth middleware: requires auth (evidence: `src/lib/platform.functions.ts`)
- Exam authoring → Admin operations: uses admin operations (evidence: `src/components/admin/ExamEditor.tsx`)
- Exam authoring → Assessment services: uses platform services (evidence: `src/components/admin/ExamEditor.tsx`)
- Question pools & blueprints → Admin operations: manages pools
- Participant / admin → Play experiences: starts activities (evidence: `README.md`)
- Play experiences → Play operations: invokes (evidence: `src/routes/_authenticated/play.session.$sessionId.tsx`)
- Play operations → Play session engine: delegates to (evidence: `src/lib/play.functions.ts`)
- Play operations → Live Arena: dispatches Arena (evidence: `src/lib/play.functions.ts`)
- Play operations → Pulse activities: dispatches Pulse
- Play session engine → Progress & rewards: uses reward logic
- Route registry → Authenticated routes: registers route (evidence: `src/routeTree.gen.ts`)
- Sign-in & callback → Supabase client: uses auth client (evidence: `src/routes/auth.tsx`)
- Assessment services → Server auth middleware: protects functions (evidence: `src/lib/platform.functions.ts`)
- Assessment services → Scoring & attempts: delegates assessment work (evidence: `src/lib/platform.functions.ts`)
- Assessment services → Privileged database client: uses privileged access (evidence: `src/lib/platform.functions.ts`)
- Scoring & attempts → Supabase: reads and writes
- Supabase client → Supabase: connects to (evidence: `src/integrations/supabase/client.ts`)
- Privileged database client → Supabase: connects with service role (evidence: `src/integrations/supabase/client.server.ts`)
- Server auth middleware → Supabase: validates user (evidence: `src/integrations/supabase/auth-middleware.ts`)
- Participant / admin → AI insights service: requests insights (evidence: `README.md`)
- AI insights service → Gemini / AI gateway: uses model provider (evidence: `README.md`)
- Auth email hook → Resend: sends auth email (evidence: `README.md`)
- Participant / admin → Help center & bot: asks for help
