# marvin101/id_card_backend architecture

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

- Interactive diagram: https://gitdiagram.com/marvin101/id_card_backend
- Repository: https://github.com/marvin101/id_card_backend

## Overview

CampusID is a FastAPI backend that powers school-scoped identity-card workflows for a Flutter client. The main path is authenticated school access, school and academic setup, student or Teacher/Staff record management, then card-template and print workflows; verification and Public Forms provide public-facing paths. Imports, grids, custom fields, audit history, and managed photos support those stages. The README documents broad capabilities, but only selected source was sampled, so links for unsampled endpoint internals are limited to documented boundaries.

Main entry points: [`app/main.py`](https://github.com/marvin101/id_card_backend/blob/main/app/main.py) (FastAPI service), [`app/core/database.py`](https://github.com/marvin101/id_card_backend/blob/main/app/core/database.py) (PostgreSQL), [`app/core/file_storage.py`](https://github.com/marvin101/id_card_backend/blob/main/app/core/file_storage.py) (Media handling), [`app/api/auth.py`](https://github.com/marvin101/id_card_backend/blob/main/app/api/auth.py) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API entry"]
  node_api["FastAPI service<br/>[main.py]"]
end

subgraph group_identity["Identity and access"]
  node_auth["Authentication<br/>[auth.py]"]
  node_session["Session management<br/>[auth_sessions.py]"]
  node_users["Users and access<br/>[users.py]"]
end

subgraph group_records["School records"]
  node_schools["Schools<br/>[schools.py]"]
  node_academics["Academic structure"]
  node_students["Student records<br/>[students.py]"]
  node_personnel["Personnel records<br/>[personnel.py]"]
  node_fields["Custom fields<br/>[student_fields.py]"]
  node_personnel_fields["Personnel fields"]
end

subgraph group_cardflows["Card workflows"]
  node_student_import["Student imports<br/>[student_imports.py]"]
  node_personnel_import["Personnel imports"]
  node_grids["Spreadsheet grids<br/>[student_grid.py]"]
  node_personnel_grid["Personnel grid<br/>[personnel_grid.py]"]
  node_templates["Card templates<br/>[card_templates.py]"]
  node_forms["Public Forms<br/>[public_forms.py]"]
  node_verification["Public verification"]
end

subgraph group_persistence["Persistence and media"]
  node_database[("PostgreSQL<br/>[database.py]")]
  node_storage[("Supabase Storage")]
  node_file_storage["Media handling<br/>[file_storage.py]"]
end

node_client(("Flutter client"))

node_client -->|"sends requests"| node_api
node_api -->|"dispatches auth"| node_auth
node_api -->|"dispatches user routes"| node_users
node_api -->|"dispatches school routes"| node_schools
node_api -->|"dispatches academic routes"| node_academics
node_api -->|"dispatches student routes"| node_students
node_api -->|"dispatches personnel routes"| node_personnel
node_api -->|"dispatches imports"| node_student_import
node_api -->|"dispatches imports"| node_personnel_import
node_api -->|"dispatches grid routes"| node_grids
node_api -->|"dispatches grid routes"| node_personnel_grid
node_api -->|"dispatches templates"| node_templates
node_api -->|"dispatches form routes"| node_forms
node_api -->|"dispatches verification"| node_verification
node_auth -->|"starts sessions"| node_session
node_auth -->|"reads users"| node_database
node_session -->|"stores sessions"| node_database
node_academics -->|"reads and writes"| node_database
node_students -->|"reads and writes"| node_database
node_personnel -->|"reads and writes"| node_database
node_schools -->|"reads and writes"| node_database
node_users -->|"reads and writes"| node_database
node_student_import -->|"commits records"| node_database
node_personnel_import -->|"commits records"| node_database
node_grids -->|"reads and patches"| node_database
node_personnel_grid -->|"reads and patches"| node_database
node_templates -->|"stores templates"| node_database
node_forms -->|"stores submissions"| node_database
node_verification -->|"reads disclosures"| node_database
node_students -->|"manages photos"| node_file_storage
node_personnel -->|"manages photos"| node_file_storage
node_file_storage -->|"uploads media"| node_storage
node_schools -->|"manages logos"| node_file_storage

click node_api "https://github.com/marvin101/id_card_backend/blob/main/app/main.py"
click node_auth "https://github.com/marvin101/id_card_backend/blob/main/app/api/auth.py"
click node_session "https://github.com/marvin101/id_card_backend/blob/main/app/core/auth_sessions.py"
click node_users "https://github.com/marvin101/id_card_backend/blob/main/app/api/users.py"
click node_schools "https://github.com/marvin101/id_card_backend/blob/main/app/api/schools.py"
click node_academics "https://github.com/marvin101/id_card_backend/blob/main/app/api/academic_sessions.py"
click node_students "https://github.com/marvin101/id_card_backend/blob/main/app/api/students.py"
click node_personnel "https://github.com/marvin101/id_card_backend/blob/main/app/api/personnel.py"
click node_fields "https://github.com/marvin101/id_card_backend/blob/main/app/api/student_fields.py"
click node_personnel_fields "https://github.com/marvin101/id_card_backend/blob/main/app/api/personnel_fields.py"
click node_student_import "https://github.com/marvin101/id_card_backend/blob/main/app/api/student_imports.py"
click node_personnel_import "https://github.com/marvin101/id_card_backend/blob/main/app/api/personnel_imports.py"
click node_grids "https://github.com/marvin101/id_card_backend/blob/main/app/api/student_grid.py"
click node_personnel_grid "https://github.com/marvin101/id_card_backend/blob/main/app/api/personnel_grid.py"
click node_templates "https://github.com/marvin101/id_card_backend/blob/main/app/api/card_templates.py"
click node_forms "https://github.com/marvin101/id_card_backend/blob/main/app/api/public_forms.py"
click node_verification "https://github.com/marvin101/id_card_backend/blob/main/app/api/public_verification.py"
click node_database "https://github.com/marvin101/id_card_backend/blob/main/app/core/database.py"
click node_file_storage "https://github.com/marvin101/id_card_backend/blob/main/app/core/file_storage.py"

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_api,node_client toneBlue
class node_auth,node_session,node_users toneAmber
class node_schools,node_academics,node_students,node_personnel,node_fields,node_personnel_fields toneMint
class node_student_import,node_personnel_import,node_grids,node_personnel_grid,node_templates,node_forms,node_verification toneRose
class node_database,node_storage,node_file_storage toneIndigo
```

## Components

### API entry

- [FastAPI service](https://github.com/marvin101/id_card_backend/blob/main/app/main.py): `app/main.py`

### Identity and access

- [Authentication](https://github.com/marvin101/id_card_backend/blob/main/app/api/auth.py): `app/api/auth.py`
- [Session management](https://github.com/marvin101/id_card_backend/blob/main/app/core/auth_sessions.py): `app/core/auth_sessions.py`
- [Users and access](https://github.com/marvin101/id_card_backend/blob/main/app/api/users.py): `app/api/users.py`

### School records

- [Schools](https://github.com/marvin101/id_card_backend/blob/main/app/api/schools.py): `app/api/schools.py`
- [Academic structure](https://github.com/marvin101/id_card_backend/blob/main/app/api/academic_sessions.py): `app/api/academic_sessions.py`
- [Student records](https://github.com/marvin101/id_card_backend/blob/main/app/api/students.py): `app/api/students.py`
- [Personnel records](https://github.com/marvin101/id_card_backend/blob/main/app/api/personnel.py): `app/api/personnel.py`
- [Custom fields](https://github.com/marvin101/id_card_backend/blob/main/app/api/student_fields.py): `app/api/student_fields.py`
- [Personnel fields](https://github.com/marvin101/id_card_backend/blob/main/app/api/personnel_fields.py): `app/api/personnel_fields.py`

### Card workflows

- [Student imports](https://github.com/marvin101/id_card_backend/blob/main/app/api/student_imports.py): `app/api/student_imports.py`
- [Personnel imports](https://github.com/marvin101/id_card_backend/blob/main/app/api/personnel_imports.py): `app/api/personnel_imports.py`
- [Spreadsheet grids](https://github.com/marvin101/id_card_backend/blob/main/app/api/student_grid.py): `app/api/student_grid.py`
- [Personnel grid](https://github.com/marvin101/id_card_backend/blob/main/app/api/personnel_grid.py): `app/api/personnel_grid.py`
- [Card templates](https://github.com/marvin101/id_card_backend/blob/main/app/api/card_templates.py): `app/api/card_templates.py`
- [Public Forms](https://github.com/marvin101/id_card_backend/blob/main/app/api/public_forms.py): `app/api/public_forms.py`
- [Public verification](https://github.com/marvin101/id_card_backend/blob/main/app/api/public_verification.py): `app/api/public_verification.py`

### Persistence and media

- [PostgreSQL](https://github.com/marvin101/id_card_backend/blob/main/app/core/database.py): `app/core/database.py`
- **Supabase Storage**
- [Media handling](https://github.com/marvin101/id_card_backend/blob/main/app/core/file_storage.py): `app/core/file_storage.py`

### Other components

- **Flutter client**

## Connections

- Flutter client → FastAPI service: sends requests
- FastAPI service → Authentication: dispatches auth
- FastAPI service → Users and access: dispatches user routes
- FastAPI service → Schools: dispatches school routes
- FastAPI service → Academic structure: dispatches academic routes
- FastAPI service → Student records: dispatches student routes
- FastAPI service → Personnel records: dispatches personnel routes
- FastAPI service → Student imports: dispatches imports
- FastAPI service → Personnel imports: dispatches imports
- FastAPI service → Spreadsheet grids: dispatches grid routes
- FastAPI service → Personnel grid: dispatches grid routes
- FastAPI service → Card templates: dispatches templates
- FastAPI service → Public Forms: dispatches form routes
- FastAPI service → Public verification: dispatches verification
- Authentication → Session management: starts sessions
- Authentication → PostgreSQL: reads users
- Session management → PostgreSQL: stores sessions
- Academic structure → PostgreSQL: reads and writes
- Student records → PostgreSQL: reads and writes
- Personnel records → PostgreSQL: reads and writes
- Schools → PostgreSQL: reads and writes
- Users and access → PostgreSQL: reads and writes
- Student imports → PostgreSQL: commits records
- Personnel imports → PostgreSQL: commits records
- Spreadsheet grids → PostgreSQL: reads and patches
- Personnel grid → PostgreSQL: reads and patches
- Card templates → PostgreSQL: stores templates
- Public Forms → PostgreSQL: stores submissions
- Public verification → PostgreSQL: reads disclosures
- Student records → Media handling: manages photos
- Personnel records → Media handling: manages photos
- Media handling → Supabase Storage: uploads media
- Schools → Media handling: manages logos