# horrid-12/student-analytics architecture

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

- Interactive diagram: https://gitdiagram.com/horrid-12/student-analytics
- Repository: https://github.com/horrid-12/student-analytics

## Overview

Student Analytics Platform is a server-rendered FastAPI application for college cohorts. Its primary flow is account signup and role-gated access, student onboarding and staff approval, GitHub synchronization into account snapshots, then dashboard payloads and rendered pages. Additional branches cover verification, support tickets and notifications, and HackerRank insights. The graph follows the README and SOURCE INDEX; some feature implementations were not sampled, so documented but unverified links are dashed.

Main entry points: [`app/main.py`](https://github.com/horrid-12/student-analytics/blob/main/app/main.py) (HTTP routes), [`app/views.py`](https://github.com/horrid-12/student-analytics/blob/main/app/views.py) (Page payloads), [`app/db.py`](https://github.com/horrid-12/student-analytics/blob/main/app/db.py) (Application data store), [`app/sync.py`](https://github.com/horrid-12/student-analytics/blob/main/app/sync.py) (Fleet synchronization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web and dashboards"]
  node_main["HTTP routes<br/>[main.py]"]
  node_views["Page payloads<br/>[views.py]"]
  node_templates["Dashboard pages"]
  node_charts["Charts<br/>[charts.py]"]
end

subgraph group_identity["Identity and onboarding"]
  node_auth["Sessions and roles<br/>[auth.py]"]
  node_oauth["OAuth providers<br/>[google_oauth.py]"]
  node_accounts_auth["Account onboarding<br/>[accounts.py]"]
end

subgraph group_analytics["Sync and analytics"]
  node_sync["Fleet synchronization<br/>[sync.py]"]
  node_services["GitHub analytics<br/>[services.py]"]
  node_ghclient["GitHub transport<br/>[github_client.py]"]
end

subgraph group_persistence["Persistence"]
  node_snapshots["Account snapshots<br/>[accounts.py]"]
  node_db[("Application data store<br/>[db.py]")]
  node_database[("Postgres connection layer<br/>[database.py]")]
end

subgraph group_features["Student services"]
  node_crosscheck["Workbook verification<br/>[crosscheck.py]"]
  node_support["Support tickets<br/>[support.py]"]
  node_weekly["Weekly announcements<br/>[weekly.py]"]
  node_hackerrank["HackerRank insights<br/>[client.py]"]
  node_hrservice["HackerRank profile service<br/>[service.py]"]
end

node_user(("Student / staff"))
node_github{{"GitHub API"}}
node_hackerrank_api{{"HackerRank API"}}

node_user -->|"uses pages"| node_main
node_main -->|"checks access"| node_auth
node_main -->|"routes OAuth"| node_oauth
node_main -->|"handles onboarding"| node_accounts_auth
node_main -->|"starts sync"| node_sync
node_main -->|"builds page data"| node_views
node_views -->|"renders pages"| node_templates
node_views -.->|"uses chart helpers"| node_charts
node_sync -->|"fetches analytics"| node_services
node_services -->|"requests API data"| node_ghclient
node_ghclient -->|"calls API"| node_github
node_sync -->|"stores snapshots"| node_snapshots
node_snapshots -->|"reads and writes"| node_db
node_db -->|"uses connection pool"| node_database
node_views -->|"loads page data"| node_db
node_main -->|"routes verification"| node_crosscheck
node_crosscheck -->|"normalizes GitHub identity"| node_services
node_crosscheck -->|"persists references"| node_db
node_main -->|"routes tickets"| node_support
node_main -->|"routes announcements"| node_weekly
node_main -->|"routes insights"| node_hackerrank
node_hackerrank -->|"uses profile service"| node_hrservice
node_hrservice -.->|"fetches profile data"| node_hackerrank_api

click node_main "https://github.com/horrid-12/student-analytics/blob/main/app/main.py"
click node_views "https://github.com/horrid-12/student-analytics/blob/main/app/views.py"
click node_templates "https://github.com/horrid-12/student-analytics/tree/main/app/templates"
click node_charts "https://github.com/horrid-12/student-analytics/blob/main/app/charts.py"
click node_auth "https://github.com/horrid-12/student-analytics/blob/main/app/auth.py"
click node_oauth "https://github.com/horrid-12/student-analytics/blob/main/app/google_oauth.py"
click node_accounts_auth "https://github.com/horrid-12/student-analytics/blob/main/app/accounts.py"
click node_sync "https://github.com/horrid-12/student-analytics/blob/main/app/sync.py"
click node_services "https://github.com/horrid-12/student-analytics/blob/main/app/services.py"
click node_ghclient "https://github.com/horrid-12/student-analytics/blob/main/app/github_client.py"
click node_snapshots "https://github.com/horrid-12/student-analytics/blob/main/app/accounts.py"
click node_db "https://github.com/horrid-12/student-analytics/blob/main/app/db.py"
click node_database "https://github.com/horrid-12/student-analytics/blob/main/app/database.py"
click node_crosscheck "https://github.com/horrid-12/student-analytics/blob/main/app/crosscheck.py"
click node_support "https://github.com/horrid-12/student-analytics/blob/main/app/support.py"
click node_weekly "https://github.com/horrid-12/student-analytics/blob/main/app/weekly.py"
click node_hackerrank "https://github.com/horrid-12/student-analytics/blob/main/app/hackerrank_client/client.py"
click node_hrservice "https://github.com/horrid-12/student-analytics/blob/main/app/hackerrank_client/service.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_main,node_views,node_templates,node_charts toneBlue
class node_auth,node_oauth,node_accounts_auth toneAmber
class node_sync,node_services,node_ghclient,node_github,node_hackerrank_api toneMint
class node_snapshots,node_db,node_database toneRose
class node_crosscheck,node_support,node_weekly,node_hackerrank,node_hrservice,node_user toneIndigo
```

## Components

### Web and dashboards

- [HTTP routes](https://github.com/horrid-12/student-analytics/blob/main/app/main.py): `app/main.py`
- [Page payloads](https://github.com/horrid-12/student-analytics/blob/main/app/views.py): `app/views.py`
- [Dashboard pages](https://github.com/horrid-12/student-analytics/tree/main/app/templates): `app/templates`
- [Charts](https://github.com/horrid-12/student-analytics/blob/main/app/charts.py): `app/charts.py`

### Identity and onboarding

- [Sessions and roles](https://github.com/horrid-12/student-analytics/blob/main/app/auth.py): `app/auth.py`
- [OAuth providers](https://github.com/horrid-12/student-analytics/blob/main/app/google_oauth.py): `app/google_oauth.py`
- [Account onboarding](https://github.com/horrid-12/student-analytics/blob/main/app/accounts.py): `app/accounts.py`

### Sync and analytics

- [Fleet synchronization](https://github.com/horrid-12/student-analytics/blob/main/app/sync.py): `app/sync.py`
- [GitHub analytics](https://github.com/horrid-12/student-analytics/blob/main/app/services.py): `app/services.py`
- [GitHub transport](https://github.com/horrid-12/student-analytics/blob/main/app/github_client.py): `app/github_client.py`

### Persistence

- [Account snapshots](https://github.com/horrid-12/student-analytics/blob/main/app/accounts.py): `app/accounts.py`
- [Application data store](https://github.com/horrid-12/student-analytics/blob/main/app/db.py): `app/db.py`
- [Postgres connection layer](https://github.com/horrid-12/student-analytics/blob/main/app/database.py): `app/database.py`

### Student services

- [Workbook verification](https://github.com/horrid-12/student-analytics/blob/main/app/crosscheck.py): `app/crosscheck.py`
- [Support tickets](https://github.com/horrid-12/student-analytics/blob/main/app/support.py): `app/support.py`
- [Weekly announcements](https://github.com/horrid-12/student-analytics/blob/main/app/weekly.py): `app/weekly.py`
- [HackerRank insights](https://github.com/horrid-12/student-analytics/blob/main/app/hackerrank_client/client.py): `app/hackerrank_client/client.py`
- [HackerRank profile service](https://github.com/horrid-12/student-analytics/blob/main/app/hackerrank_client/service.py): `app/hackerrank_client/service.py`

### Other components

- **Student / staff**
- **GitHub API**
- **HackerRank API**

## Connections

- Student / staff → HTTP routes: uses pages (evidence: `README.md`)
- HTTP routes → Sessions and roles: checks access (evidence: `README.md`)
- HTTP routes → OAuth providers: routes OAuth (evidence: `app/main.py`)
- HTTP routes → Account onboarding: handles onboarding (evidence: `app/main.py`)
- HTTP routes → Fleet synchronization: starts sync (evidence: `README.md`)
- HTTP routes → Page payloads: builds page data (evidence: `README.md`)
- Page payloads → Dashboard pages: renders pages (evidence: `README.md`)
- Page payloads → Charts: uses chart helpers
- Fleet synchronization → GitHub analytics: fetches analytics (evidence: `app/sync.py`)
- GitHub analytics → GitHub transport: requests API data (evidence: `app/services.py`)
- GitHub transport → GitHub API: calls API (evidence: `README.md`)
- Fleet synchronization → Account snapshots: stores snapshots (evidence: `app/sync.py`)
- Account snapshots → Application data store: reads and writes (evidence: `app/accounts.py`)
- Application data store → Postgres connection layer: uses connection pool (evidence: `app/db.py`)
- Page payloads → Application data store: loads page data (evidence: `app/views.py`)
- HTTP routes → Workbook verification: routes verification (evidence: `app/main.py`)
- Workbook verification → GitHub analytics: normalizes GitHub identity (evidence: `app/crosscheck.py`)
- Workbook verification → Application data store: persists references (evidence: `app/crosscheck.py`)
- HTTP routes → Support tickets: routes tickets (evidence: `app/main.py`)
- HTTP routes → Weekly announcements: routes announcements (evidence: `app/main.py`)
- HTTP routes → HackerRank insights: routes insights (evidence: `app/main.py`)
- HackerRank insights → HackerRank profile service: uses profile service (evidence: `app/hackerrank_client/__init__.py`)
- HackerRank profile service → HackerRank API: fetches profile data
