# amitkio/insights architecture

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

- Interactive diagram: https://gitdiagram.com/amitkio/insights
- Repository: https://github.com/amitkio/insights

## Overview

Insights digitizes university result books: administrators upload PDFs, the backend extracts student and subject grades, stores results in isolated production or guest databases, and role-specific users explore dashboards, analytics, exports, and reports. The frontend also supports authentication, account and college administration, and public trend exploration. The README documents capabilities beyond the sampled source; those branches are represented at the nearest supported module or directory, while uncertain internal wiring is omitted.

Main entry points: [`backend/main.py`](https://github.com/amitkio/insights/blob/main/backend/main.py) (REST API), [`backend/services/database.py`](https://github.com/amitkio/insights/blob/main/backend/services/database.py) (Database sessions), [`frontend/app/components`](https://github.com/amitkio/insights/tree/main/frontend/app/components) (Role dashboards), [`frontend/app/context/AuthContext.tsx`](https://github.com/amitkio/insights/blob/main/frontend/app/context/AuthContext.tsx) (Client authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web experience"]
  node_routes["Application routes<br/>[routes.ts]"]
  node_dashboards["Role dashboards"]
  node_authui["Client authentication<br/>[AuthContext.tsx]"]
  node_resultsclient["Results API client<br/>[results.ts]"]
  node_exports["Result exports<br/>[result-manager.ts]"]
end

subgraph group_backend["Backend services"]
  node_api["REST API<br/>[main.py]"]
  node_parser["PDF parsing and SGPA<br/>[helper.py]"]
  node_crud["Data operations<br/>[crud.py]"]
  node_metrics["Analytics rollups<br/>[metrics.py]"]
end

subgraph group_data["Result data"]
  node_models["Domain records"]
  node_dbconfig["Database sessions<br/>[database.py]"]
  node_production[("Production PostgreSQL")]
  node_guestdb[("Guest PostgreSQL")]
end

subgraph group_identity["Identity and analytics"]
  node_auth["JWT and Firebase auth<br/>[auth.py]"]
  node_firebase["Firebase authentication"]
  node_googlekeys["Google signing keys"]
end

node_browser(("Browser users"))

node_browser -->|"opens views"| node_routes
node_routes -->|"renders"| node_dashboards
node_dashboards -->|"requests results"| node_resultsclient
node_resultsclient -->|"calls API"| node_api
node_dashboards -->|"prepares exports"| node_exports
node_exports -->|"fetches results"| node_resultsclient
node_browser -->|"signs in"| node_authui
node_authui -.->|"gets identity token"| node_firebase
node_authui -->|"submits credentials"| node_api
node_api -->|"authenticates"| node_auth
node_auth -.->|"fetches keys"| node_googlekeys
node_api -->|"parses uploads"| node_parser
node_api -->|"manages records"| node_crud
node_api -->|"records and rolls up"| node_metrics
node_api -->|"opens sessions"| node_dbconfig
node_auth -->|"uses production session"| node_dbconfig
node_dbconfig -->|"routes standard data"| node_production
node_dbconfig -->|"routes guest data"| node_guestdb
node_crud -->|"uses records"| node_models
node_metrics -->|"aggregates events"| node_models
node_parser -->|"produces result data"| node_models

click node_routes "https://github.com/amitkio/insights/blob/main/frontend/app/routes.ts"
click node_dashboards "https://github.com/amitkio/insights/tree/main/frontend/app/components"
click node_authui "https://github.com/amitkio/insights/blob/main/frontend/app/context/AuthContext.tsx"
click node_resultsclient "https://github.com/amitkio/insights/blob/main/frontend/app/api/results.ts"
click node_exports "https://github.com/amitkio/insights/blob/main/frontend/app/utils/result-manager.ts"
click node_api "https://github.com/amitkio/insights/blob/main/backend/main.py"
click node_parser "https://github.com/amitkio/insights/blob/main/backend/helper.py"
click node_crud "https://github.com/amitkio/insights/blob/main/backend/services/crud.py"
click node_metrics "https://github.com/amitkio/insights/blob/main/backend/services/metrics.py"
click node_auth "https://github.com/amitkio/insights/blob/main/backend/services/auth.py"
click node_models "https://github.com/amitkio/insights/tree/main/backend/models"
click node_dbconfig "https://github.com/amitkio/insights/blob/main/backend/services/database.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_routes,node_dashboards,node_authui,node_resultsclient,node_exports,node_browser toneBlue
class node_api,node_parser,node_crud,node_metrics toneAmber
class node_models,node_dbconfig,node_production,node_guestdb toneMint
class node_auth,node_firebase,node_googlekeys toneRose
```

## Components

### Web experience

- [Application routes](https://github.com/amitkio/insights/blob/main/frontend/app/routes.ts): `frontend/app/routes.ts`
- [Role dashboards](https://github.com/amitkio/insights/tree/main/frontend/app/components): `frontend/app/components`
- [Client authentication](https://github.com/amitkio/insights/blob/main/frontend/app/context/AuthContext.tsx): `frontend/app/context/AuthContext.tsx`
- [Results API client](https://github.com/amitkio/insights/blob/main/frontend/app/api/results.ts): `frontend/app/api/results.ts`
- [Result exports](https://github.com/amitkio/insights/blob/main/frontend/app/utils/result-manager.ts): `frontend/app/utils/result-manager.ts`

### Backend services

- [REST API](https://github.com/amitkio/insights/blob/main/backend/main.py): `backend/main.py`
- [PDF parsing and SGPA](https://github.com/amitkio/insights/blob/main/backend/helper.py): `backend/helper.py`
- [Data operations](https://github.com/amitkio/insights/blob/main/backend/services/crud.py): `backend/services/crud.py`
- [Analytics rollups](https://github.com/amitkio/insights/blob/main/backend/services/metrics.py): `backend/services/metrics.py`

### Result data

- [Domain records](https://github.com/amitkio/insights/tree/main/backend/models): `backend/models`
- [Database sessions](https://github.com/amitkio/insights/blob/main/backend/services/database.py): `backend/services/database.py`
- **Production PostgreSQL**
- **Guest PostgreSQL**

### Identity and analytics

- [JWT and Firebase auth](https://github.com/amitkio/insights/blob/main/backend/services/auth.py): `backend/services/auth.py`
- **Firebase authentication**
- **Google signing keys**

### Other components

- **Browser users**

## Connections

- Browser users → Application routes: opens views
- Application routes → Role dashboards: renders
- Role dashboards → Results API client: requests results
- Results API client → REST API: calls API
- Role dashboards → Result exports: prepares exports
- Result exports → Results API client: fetches results
- Browser users → Client authentication: signs in
- Client authentication → Firebase authentication: gets identity token
- Client authentication → REST API: submits credentials
- REST API → JWT and Firebase auth: authenticates
- JWT and Firebase auth → Google signing keys: fetches keys
- REST API → PDF parsing and SGPA: parses uploads
- REST API → Data operations: manages records
- REST API → Analytics rollups: records and rolls up
- REST API → Database sessions: opens sessions
- JWT and Firebase auth → Database sessions: uses production session
- Database sessions → Production PostgreSQL: routes standard data
- Database sessions → Guest PostgreSQL: routes guest data
- Data operations → Domain records: uses records
- Analytics rollups → Domain records: aggregates events
- PDF parsing and SGPA → Domain records: produces result data