# tomfrx12/hero-sos-api architecture

> Architecture diagram of the GitHub repository tomfrx12/hero-sos-api, 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/tomfrx12/hero-sos-api
- Repository: https://github.com/tomfrx12/hero-sos-api

## Overview

Hero SOS API is the backend for a civic incident-reporting and superhero-response service. Citizens register, report incidents, and rate heroes; heroes manage incidents and interventions; administrators moderate users, incidents, reviews, articles, and film submissions. The API also supports profiles, newsletter subscriptions, statistics, and a superhero video library. The excerpts show route registration and several controller-to-service relationships; for unsampled controllers, capabilities come from the README and edges are omitted where their wiring is not evidenced.

Main entry points: [`src/services/prisma.ts`](https://github.com/tomfrx12/hero-sos-api/blob/main/src/services/prisma.ts) (Prisma client), [`src/index.ts`](https://github.com/tomfrx12/hero-sos-api/blob/main/src/index.ts) (API entry), [`src/routes/admin.routes.ts`](https://github.com/tomfrx12/hero-sos-api/blob/main/src/routes/admin.routes.ts) (Admin routes), [`src/middlewares/authentifier.ts`](https://github.com/tomfrx12/hero-sos-api/blob/main/src/middlewares/authentifier.ts) (Authentication and roles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_entry["API entry<br/>[index.ts]"]
  node_authroutes["Auth routes<br/>[auth.routes.ts]"]
  node_incidentroutes["Incident routes<br/>[incident.routes.ts]"]
  node_adminroutes["Admin routes<br/>[admin.routes.ts]"]
  node_moroutes["My-account routes<br/>[moi.routes.ts]"]
  node_vilainroutes["Villain routes<br/>[vilains.routes.ts]"]
end

subgraph group_accounts["Accounts and access"]
  node_auth["Registration and login<br/>[auth.controleur.ts]"]
  node_profile["Account and hero profile<br/>[moi.controleur.ts]"]
  node_authmw["Authentication and roles<br/>[authentifier.ts]"]
end

subgraph group_response["Incidents and heroes"]
  node_incidents["Incident reporting"]
  node_heroes["Hero directory"]
  node_villains["Villain directory"]
  node_admin["Administration"]
  node_stats["Statistics"]
end

subgraph group_content["Community content"]
  node_articles["Blog articles"]
  node_video["Hero video library"]
  node_newsletter["Newsletter"]
end

subgraph group_infra["Shared services"]
  node_db[("PostgreSQL<br/>[schema.prisma]")]
  node_prismasvc["Prisma client<br/>[prisma.ts]"]
  node_mail["Email service<br/>[mail.ts]"]
  node_token["JWT service<br/>[token.ts]"]
  node_upload["Image uploads<br/>[upload.ts]"]
  node_ratelimit["Request limits<br/>[limiteurs.ts]"]
end

node_frontend(("Web frontend"))
node_smtp["SMTP provider"]
node_tmdb["TMDB"]

node_frontend -->|"calls API"| node_entry
node_entry -->|"mounts"| node_authroutes
node_entry -->|"mounts"| node_incidentroutes
node_entry -->|"mounts"| node_adminroutes
node_entry -->|"mounts"| node_moroutes
node_entry -->|"mounts"| node_vilainroutes
node_entry -->|"applies"| node_ratelimit
node_authroutes -->|"routes to"| node_auth
node_incidentroutes -->|"routes to"| node_incidents
node_adminroutes -->|"routes to"| node_admin
node_adminroutes -->|"routes to"| node_articles
node_adminroutes -->|"routes to"| node_video
node_moroutes -->|"routes to"| node_auth
node_moroutes -->|"routes to"| node_profile
node_moroutes -->|"authenticates"| node_authmw
node_vilainroutes -->|"routes to"| node_villains
node_vilainroutes -->|"authorizes"| node_authmw
node_adminroutes -->|"authorizes"| node_authmw
node_incidentroutes -->|"authorizes"| node_authmw
node_authroutes -->|"authenticates"| node_authmw
node_authmw -->|"reads token"| node_token
node_auth -->|"reads and writes"| node_prismasvc
node_auth -->|"creates token"| node_token
node_auth -->|"sends email"| node_mail
node_profile -->|"uses"| node_prismasvc
node_incidents -->|"uses"| node_prismasvc
node_incidents -->|"sends email"| node_mail
node_heroes -->|"uses"| node_prismasvc
node_villains -->|"uses"| node_prismasvc
node_admin -->|"uses"| node_prismasvc
node_admin -->|"sends email"| node_mail
node_stats -->|"uses"| node_prismasvc
node_articles -->|"uses"| node_prismasvc
node_video -->|"uses"| node_prismasvc
node_newsletter -->|"uses"| node_prismasvc
node_prismasvc -->|"queries"| node_db
node_mail -->|"sends mail"| node_smtp
node_mail -->|"queries recipients"| node_prismasvc
node_adminroutes -->|"uses upload"| node_upload
node_moroutes -->|"uses upload"| node_upload
node_vilainroutes -->|"uses upload"| node_upload
node_video -.->|"searches films"| node_tmdb

click node_entry "https://github.com/tomfrx12/hero-sos-api/blob/main/src/index.ts"
click node_authroutes "https://github.com/tomfrx12/hero-sos-api/blob/main/src/routes/auth.routes.ts"
click node_incidentroutes "https://github.com/tomfrx12/hero-sos-api/blob/main/src/routes/incident.routes.ts"
click node_adminroutes "https://github.com/tomfrx12/hero-sos-api/blob/main/src/routes/admin.routes.ts"
click node_moroutes "https://github.com/tomfrx12/hero-sos-api/blob/main/src/routes/moi.routes.ts"
click node_vilainroutes "https://github.com/tomfrx12/hero-sos-api/blob/main/src/routes/vilains.routes.ts"
click node_auth "https://github.com/tomfrx12/hero-sos-api/blob/main/src/controleurs/auth.controleur.ts"
click node_profile "https://github.com/tomfrx12/hero-sos-api/blob/main/src/controleurs/moi.controleur.ts"
click node_authmw "https://github.com/tomfrx12/hero-sos-api/blob/main/src/middlewares/authentifier.ts"
click node_incidents "https://github.com/tomfrx12/hero-sos-api/blob/main/src/controleurs/incident.controleur.ts"
click node_heroes "https://github.com/tomfrx12/hero-sos-api/blob/main/src/controleurs/heros.controleur.ts"
click node_villains "https://github.com/tomfrx12/hero-sos-api/blob/main/src/controleurs/vilains.controleur.ts"
click node_admin "https://github.com/tomfrx12/hero-sos-api/blob/main/src/controleurs/admin.controleur.ts"
click node_stats "https://github.com/tomfrx12/hero-sos-api/blob/main/src/controleurs/stats.controleur.ts"
click node_articles "https://github.com/tomfrx12/hero-sos-api/blob/main/src/controleurs/articles.controleur.ts"
click node_video "https://github.com/tomfrx12/hero-sos-api/blob/main/src/controleurs/videotheque.controleur.ts"
click node_newsletter "https://github.com/tomfrx12/hero-sos-api/blob/main/src/controleurs/newsletter.controleur.ts"
click node_db "https://github.com/tomfrx12/hero-sos-api/blob/main/prisma/schema.prisma"
click node_prismasvc "https://github.com/tomfrx12/hero-sos-api/blob/main/src/services/prisma.ts"
click node_mail "https://github.com/tomfrx12/hero-sos-api/blob/main/src/services/mail.ts"
click node_token "https://github.com/tomfrx12/hero-sos-api/blob/main/src/services/token.ts"
click node_upload "https://github.com/tomfrx12/hero-sos-api/blob/main/src/services/upload.ts"
click node_ratelimit "https://github.com/tomfrx12/hero-sos-api/blob/main/src/middlewares/limiteurs.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_entry,node_authroutes,node_incidentroutes,node_adminroutes,node_moroutes,node_vilainroutes,node_frontend toneBlue
class node_auth,node_profile,node_authmw toneAmber
class node_incidents,node_heroes,node_villains,node_admin,node_stats toneMint
class node_articles,node_video,node_newsletter toneRose
class node_db,node_prismasvc,node_mail,node_token,node_upload,node_ratelimit,node_smtp,node_tmdb toneIndigo
```

## Components

### HTTP API

- [API entry](https://github.com/tomfrx12/hero-sos-api/blob/main/src/index.ts): `src/index.ts`
- [Auth routes](https://github.com/tomfrx12/hero-sos-api/blob/main/src/routes/auth.routes.ts): `src/routes/auth.routes.ts`
- [Incident routes](https://github.com/tomfrx12/hero-sos-api/blob/main/src/routes/incident.routes.ts): `src/routes/incident.routes.ts`
- [Admin routes](https://github.com/tomfrx12/hero-sos-api/blob/main/src/routes/admin.routes.ts): `src/routes/admin.routes.ts`
- [My-account routes](https://github.com/tomfrx12/hero-sos-api/blob/main/src/routes/moi.routes.ts): `src/routes/moi.routes.ts`
- [Villain routes](https://github.com/tomfrx12/hero-sos-api/blob/main/src/routes/vilains.routes.ts): `src/routes/vilains.routes.ts`

### Accounts and access

- [Registration and login](https://github.com/tomfrx12/hero-sos-api/blob/main/src/controleurs/auth.controleur.ts): `src/controleurs/auth.controleur.ts`
- [Account and hero profile](https://github.com/tomfrx12/hero-sos-api/blob/main/src/controleurs/moi.controleur.ts): `src/controleurs/moi.controleur.ts`
- [Authentication and roles](https://github.com/tomfrx12/hero-sos-api/blob/main/src/middlewares/authentifier.ts): `src/middlewares/authentifier.ts`

### Incidents and heroes

- [Incident reporting](https://github.com/tomfrx12/hero-sos-api/blob/main/src/controleurs/incident.controleur.ts): `src/controleurs/incident.controleur.ts`
- [Hero directory](https://github.com/tomfrx12/hero-sos-api/blob/main/src/controleurs/heros.controleur.ts): `src/controleurs/heros.controleur.ts`
- [Villain directory](https://github.com/tomfrx12/hero-sos-api/blob/main/src/controleurs/vilains.controleur.ts): `src/controleurs/vilains.controleur.ts`
- [Administration](https://github.com/tomfrx12/hero-sos-api/blob/main/src/controleurs/admin.controleur.ts): `src/controleurs/admin.controleur.ts`
- [Statistics](https://github.com/tomfrx12/hero-sos-api/blob/main/src/controleurs/stats.controleur.ts): `src/controleurs/stats.controleur.ts`

### Community content

- [Blog articles](https://github.com/tomfrx12/hero-sos-api/blob/main/src/controleurs/articles.controleur.ts): `src/controleurs/articles.controleur.ts`
- [Hero video library](https://github.com/tomfrx12/hero-sos-api/blob/main/src/controleurs/videotheque.controleur.ts): `src/controleurs/videotheque.controleur.ts`
- [Newsletter](https://github.com/tomfrx12/hero-sos-api/blob/main/src/controleurs/newsletter.controleur.ts): `src/controleurs/newsletter.controleur.ts`

### Shared services

- [PostgreSQL](https://github.com/tomfrx12/hero-sos-api/blob/main/prisma/schema.prisma): `prisma/schema.prisma`
- [Prisma client](https://github.com/tomfrx12/hero-sos-api/blob/main/src/services/prisma.ts): `src/services/prisma.ts`
- [Email service](https://github.com/tomfrx12/hero-sos-api/blob/main/src/services/mail.ts): `src/services/mail.ts`
- [JWT service](https://github.com/tomfrx12/hero-sos-api/blob/main/src/services/token.ts): `src/services/token.ts`
- [Image uploads](https://github.com/tomfrx12/hero-sos-api/blob/main/src/services/upload.ts): `src/services/upload.ts`
- [Request limits](https://github.com/tomfrx12/hero-sos-api/blob/main/src/middlewares/limiteurs.ts): `src/middlewares/limiteurs.ts`

### Other components

- **Web frontend**
- **SMTP provider**
- **TMDB**

## Connections

- Web frontend → API entry: calls API (evidence: `README.md`)
- API entry → Auth routes: mounts (evidence: `src/index.ts`)
- API entry → Incident routes: mounts (evidence: `src/index.ts`)
- API entry → Admin routes: mounts (evidence: `src/index.ts`)
- API entry → My-account routes: mounts (evidence: `src/index.ts`)
- API entry → Villain routes: mounts (evidence: `src/index.ts`)
- API entry → Request limits: applies (evidence: `src/index.ts`)
- Auth routes → Registration and login: routes to (evidence: `src/routes/auth.routes.ts`)
- Incident routes → Incident reporting: routes to (evidence: `src/routes/incident.routes.ts`)
- Admin routes → Administration: routes to (evidence: `src/routes/admin.routes.ts`)
- Admin routes → Blog articles: routes to (evidence: `src/routes/admin.routes.ts`)
- Admin routes → Hero video library: routes to (evidence: `src/routes/admin.routes.ts`)
- My-account routes → Registration and login: routes to (evidence: `src/routes/moi.routes.ts`)
- My-account routes → Account and hero profile: routes to (evidence: `src/routes/moi.routes.ts`)
- My-account routes → Authentication and roles: authenticates (evidence: `src/routes/moi.routes.ts`)
- Villain routes → Villain directory: routes to (evidence: `src/routes/vilains.routes.ts`)
- Villain routes → Authentication and roles: authorizes (evidence: `src/routes/vilains.routes.ts`)
- Admin routes → Authentication and roles: authorizes (evidence: `src/routes/admin.routes.ts`)
- Incident routes → Authentication and roles: authorizes (evidence: `src/routes/incident.routes.ts`)
- Auth routes → Authentication and roles: authenticates (evidence: `src/routes/auth.routes.ts`)
- Authentication and roles → JWT service: reads token (evidence: `src/middlewares/authentifier.ts`)
- Registration and login → Prisma client: reads and writes (evidence: `src/controleurs/auth.controleur.ts`)
- Registration and login → JWT service: creates token (evidence: `src/controleurs/auth.controleur.ts`)
- Registration and login → Email service: sends email (evidence: `src/controleurs/auth.controleur.ts`)
- Account and hero profile → Prisma client: uses (evidence: `src/controleurs/moi.controleur.ts`)
- Incident reporting → Prisma client: uses (evidence: `src/controleurs/incident.controleur.ts`)
- Incident reporting → Email service: sends email (evidence: `src/controleurs/incident.controleur.ts`)
- Hero directory → Prisma client: uses (evidence: `src/controleurs/heros.controleur.ts`)
- Villain directory → Prisma client: uses (evidence: `src/controleurs/vilains.controleur.ts`)
- Administration → Prisma client: uses (evidence: `src/controleurs/admin.controleur.ts`)
- Administration → Email service: sends email (evidence: `src/controleurs/admin.controleur.ts`)
- Statistics → Prisma client: uses (evidence: `src/controleurs/stats.controleur.ts`)
- Blog articles → Prisma client: uses (evidence: `src/controleurs/articles.controleur.ts`)
- Hero video library → Prisma client: uses (evidence: `src/controleurs/videotheque.controleur.ts`)
- Newsletter → Prisma client: uses (evidence: `src/controleurs/newsletter.controleur.ts`)
- Prisma client → PostgreSQL: queries (evidence: `src/services/prisma.ts`)
- Email service → SMTP provider: sends mail (evidence: `src/services/mail.ts`)
- Email service → Prisma client: queries recipients (evidence: `src/services/mail.ts`)
- Admin routes → Image uploads: uses upload (evidence: `src/routes/admin.routes.ts`)
- My-account routes → Image uploads: uses upload (evidence: `src/routes/moi.routes.ts`)
- Villain routes → Image uploads: uses upload (evidence: `src/routes/vilains.routes.ts`)
- Hero video library → TMDB: searches films