# hamamebouchareb/hamame-platform architecture

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

- Interactive diagram: https://gitdiagram.com/hamamebouchareb/hamame-platform
- Repository: https://github.com/hamamebouchareb/hamame-platform

## Overview

Hamame is a study and exam-preparation platform: learners use a web app to study curriculum content, practice questions, take sessions or simulations, review progress, and manage accounts. The web client fronts an Express API; session handling includes question selection, attempts, and review/badge hooks. The API also supports AI study aids, authoring and moderation, social features, and scheduled maintenance and reminder jobs. The README is empty, so product capabilities are inferred from the tree and source index; frontend-to-API wiring and several route internals were not sampled.

Main entry points: [`src/app.ts`](https://github.com/hamamebouchareb/hamame-platform/blob/main/src/app.ts) (Express app), [`src/jobs`](https://github.com/hamamebouchareb/hamame-platform/tree/main/src/jobs) (Scheduled jobs), [`src/lib/prisma.ts`](https://github.com/hamamebouchareb/hamame-platform/blob/main/src/lib/prisma.ts) (Application database), [`src/routes/sessions.routes.ts`](https://github.com/hamamebouchareb/hamame-platform/blob/main/src/routes/sessions.routes.ts) (Practice sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["Study web app"]
  node_webapi["API client<br/>[api.ts]"]
end

subgraph group_api["API and access"]
  node_server["HTTP server<br/>[server.ts]"]
  node_app["Express app<br/>[app.ts]"]
  node_routes["API route registry<br/>[index.ts]"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_roles["Role authorization<br/>[requireRole.ts]"]
  node_validation["Request validation<br/>[validate.ts]"]
  node_errors["Error handling<br/>[errorHandler.ts]"]
  node_database[("Application database<br/>[prisma.ts]")]
  node_admin["Administration<br/>[admin.routes.ts]"]
end

subgraph group_study["Study workflows"]
  node_sessions["Practice sessions<br/>[sessions.routes.ts]"]
  node_reviewqueue["Spaced review queue<br/>[reviews.routes.ts]"]
  node_studyprogress["Progress and goals<br/>[progress.routes.ts]"]
  node_ai["AI study aids<br/>[contextual-hint.ts]"]
end

subgraph group_content["Content and community"]
  node_questions["Questions and curriculum"]
  node_authoring["Content authoring"]
  node_moderation["Content review<br/>[review.routes.ts]"]
  node_social["Community and leaderboards<br/>[friends.routes.ts]"]
end

subgraph group_operations["Jobs and integrations"]
  node_anthropic{{"Anthropic API"}}
  node_jobs["Scheduled jobs"]
  node_push["Push delivery<br/>[send.ts]"]
  node_pushservice{{"Push service"}}
end

node_learner(("Learner"))

node_learner -->|"uses"| node_web
node_web -.->|"requests data"| node_webapi
node_webapi -.->|"calls API"| node_app
node_server -->|"creates"| node_app
node_app -->|"mounts at /api"| node_routes
node_app -->|"handles errors"| node_errors
node_sessions -->|"enqueues reviews"| node_reviewqueue
node_sessions -->|"loads hint questions"| node_ai
node_ai -->|"generates hints"| node_anthropic
node_sessions -->|"reads and writes"| node_database
node_reviewqueue -->|"reads and writes"| node_database
node_moderation -->|"updates reviewed content"| node_database
node_moderation -->|"generates explanations"| node_ai
node_admin -->|"runs maintenance"| node_jobs
node_server -->|"schedules"| node_jobs
node_jobs -->|"updates records"| node_database
node_jobs -->|"sends reminders"| node_push
node_push -.->|"delivers notifications"| node_pushservice

click node_web "https://github.com/hamamebouchareb/hamame-platform/tree/main/web/src/app"
click node_webapi "https://github.com/hamamebouchareb/hamame-platform/blob/main/web/src/lib/api.ts"
click node_server "https://github.com/hamamebouchareb/hamame-platform/blob/main/src/server.ts"
click node_app "https://github.com/hamamebouchareb/hamame-platform/blob/main/src/app.ts"
click node_routes "https://github.com/hamamebouchareb/hamame-platform/blob/main/src/routes/index.ts"
click node_auth "https://github.com/hamamebouchareb/hamame-platform/blob/main/src/middleware/auth.ts"
click node_roles "https://github.com/hamamebouchareb/hamame-platform/blob/main/src/middleware/requireRole.ts"
click node_validation "https://github.com/hamamebouchareb/hamame-platform/blob/main/src/middleware/validate.ts"
click node_errors "https://github.com/hamamebouchareb/hamame-platform/blob/main/src/middleware/errorHandler.ts"
click node_database "https://github.com/hamamebouchareb/hamame-platform/blob/main/src/lib/prisma.ts"
click node_sessions "https://github.com/hamamebouchareb/hamame-platform/blob/main/src/routes/sessions.routes.ts"
click node_reviewqueue "https://github.com/hamamebouchareb/hamame-platform/blob/main/src/routes/reviews.routes.ts"
click node_studyprogress "https://github.com/hamamebouchareb/hamame-platform/blob/main/src/routes/progress.routes.ts"
click node_questions "https://github.com/hamamebouchareb/hamame-platform/blob/main/src/routes/questions.routes.ts"
click node_authoring "https://github.com/hamamebouchareb/hamame-platform/blob/main/src/routes/authoring.routes.ts"
click node_moderation "https://github.com/hamamebouchareb/hamame-platform/blob/main/src/routes/review.routes.ts"
click node_social "https://github.com/hamamebouchareb/hamame-platform/blob/main/src/routes/friends.routes.ts"
click node_ai "https://github.com/hamamebouchareb/hamame-platform/blob/main/src/lib/ai/contextual-hint.ts"
click node_jobs "https://github.com/hamamebouchareb/hamame-platform/tree/main/src/jobs"
click node_push "https://github.com/hamamebouchareb/hamame-platform/blob/main/src/lib/push/send.ts"
click node_admin "https://github.com/hamamebouchareb/hamame-platform/blob/main/src/routes/admin.routes.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_webapi toneBlue
class node_server,node_app,node_routes,node_auth,node_roles,node_validation,node_errors,node_database,node_admin toneAmber
class node_sessions,node_reviewqueue,node_studyprogress,node_ai toneMint
class node_questions,node_authoring,node_moderation,node_social toneRose
class node_anthropic,node_jobs,node_push,node_pushservice,node_learner toneIndigo
```

## Components

### Web client

- [Study web app](https://github.com/hamamebouchareb/hamame-platform/tree/main/web/src/app): `web/src/app`
- [API client](https://github.com/hamamebouchareb/hamame-platform/blob/main/web/src/lib/api.ts): `web/src/lib/api.ts`

### API and access

- [HTTP server](https://github.com/hamamebouchareb/hamame-platform/blob/main/src/server.ts): `src/server.ts`
- [Express app](https://github.com/hamamebouchareb/hamame-platform/blob/main/src/app.ts): `src/app.ts`
- [API route registry](https://github.com/hamamebouchareb/hamame-platform/blob/main/src/routes/index.ts): `src/routes/index.ts`
- [Authentication](https://github.com/hamamebouchareb/hamame-platform/blob/main/src/middleware/auth.ts): `src/middleware/auth.ts`
- [Role authorization](https://github.com/hamamebouchareb/hamame-platform/blob/main/src/middleware/requireRole.ts): `src/middleware/requireRole.ts`
- [Request validation](https://github.com/hamamebouchareb/hamame-platform/blob/main/src/middleware/validate.ts): `src/middleware/validate.ts`
- [Error handling](https://github.com/hamamebouchareb/hamame-platform/blob/main/src/middleware/errorHandler.ts): `src/middleware/errorHandler.ts`
- [Application database](https://github.com/hamamebouchareb/hamame-platform/blob/main/src/lib/prisma.ts): `src/lib/prisma.ts`
- [Administration](https://github.com/hamamebouchareb/hamame-platform/blob/main/src/routes/admin.routes.ts): `src/routes/admin.routes.ts`

### Study workflows

- [Practice sessions](https://github.com/hamamebouchareb/hamame-platform/blob/main/src/routes/sessions.routes.ts): `src/routes/sessions.routes.ts`
- [Spaced review queue](https://github.com/hamamebouchareb/hamame-platform/blob/main/src/routes/reviews.routes.ts): `src/routes/reviews.routes.ts`
- [Progress and goals](https://github.com/hamamebouchareb/hamame-platform/blob/main/src/routes/progress.routes.ts): `src/routes/progress.routes.ts`
- [AI study aids](https://github.com/hamamebouchareb/hamame-platform/blob/main/src/lib/ai/contextual-hint.ts): `src/lib/ai/contextual-hint.ts`

### Content and community

- [Questions and curriculum](https://github.com/hamamebouchareb/hamame-platform/blob/main/src/routes/questions.routes.ts): `src/routes/questions.routes.ts`
- [Content authoring](https://github.com/hamamebouchareb/hamame-platform/blob/main/src/routes/authoring.routes.ts): `src/routes/authoring.routes.ts`
- [Content review](https://github.com/hamamebouchareb/hamame-platform/blob/main/src/routes/review.routes.ts): `src/routes/review.routes.ts`
- [Community and leaderboards](https://github.com/hamamebouchareb/hamame-platform/blob/main/src/routes/friends.routes.ts): `src/routes/friends.routes.ts`

### Jobs and integrations

- **Anthropic API**
- [Scheduled jobs](https://github.com/hamamebouchareb/hamame-platform/tree/main/src/jobs): `src/jobs`
- [Push delivery](https://github.com/hamamebouchareb/hamame-platform/blob/main/src/lib/push/send.ts): `src/lib/push/send.ts`
- **Push service**

### Other components

- **Learner**

## Connections

- Learner → Study web app: uses
- Study web app → API client: requests data
- API client → Express app: calls API
- HTTP server → Express app: creates (evidence: `src/server.ts`)
- Express app → API route registry: mounts at /api (evidence: `src/app.ts`)
- Express app → Error handling: handles errors (evidence: `src/app.ts`)
- Practice sessions → Spaced review queue: enqueues reviews (evidence: `src/routes/sessions.routes.ts`)
- Practice sessions → AI study aids: loads hint questions (evidence: `src/routes/sessions.routes.ts`)
- AI study aids → Anthropic API: generates hints (evidence: `src/lib/ai/contextual-hint.ts`)
- Practice sessions → Application database: reads and writes (evidence: `src/routes/sessions.routes.ts`)
- Spaced review queue → Application database: reads and writes (evidence: `src/routes/reviews.routes.ts`)
- Content review → Application database: updates reviewed content (evidence: `src/routes/review.routes.ts`)
- Content review → AI study aids: generates explanations (evidence: `src/routes/review.routes.ts`)
- Administration → Scheduled jobs: runs maintenance (evidence: `src/routes/admin.routes.ts`)
- HTTP server → Scheduled jobs: schedules (evidence: `src/server.ts`)
- Scheduled jobs → Application database: updates records (evidence: `src/jobs/expireSubscriptions.ts`)
- Scheduled jobs → Push delivery: sends reminders (evidence: `src/jobs/sendDailyPushReminders.ts`)
- Push delivery → Push service: delivers notifications
