# art-maker-blip/phinmaed-slc-analytics architecture

> Architecture diagram of the GitHub repository art-maker-blip/phinmaed-slc-analytics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/art-maker-blip/phinmaed-slc-analytics
- Repository: https://github.com/art-maker-blip/phinmaed-slc-analytics

## Overview

PHINMAED is a role- and scope-limited student grade review application. The main workflow is to upload SIS grade CSVs, review and accept validated batches, calculate zone snapshots using approved rules, then view dashboards/reports and record deliberation or referrals. Administration manages users and reference data; audit records important actions. The graph emphasizes those domain stages and shared authorization. Some subsystem links are based on documented capabilities or indexed imports because their implementation excerpts were not provided.

Main entry points: [`lib/database.ts`](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/database.ts) (PostgreSQL access), [`lib/imports/server.ts`](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/imports/server.ts) (Grade import batches), [`lib/audit.ts`](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/audit.ts) (Audit log), [`lib/concerns/server.ts`](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/concerns/server.ts) (Concerns and referrals)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and platform"]
  node_web["Web interface<br/>[layout.tsx]"]
  node_login["Sign-in<br/>[LoginForm.tsx]"]
  node_auth["Sessions and identity<br/>[auth.ts]"]
  node_authorization["Role and scope checks<br/>[authorize.tsx]"]
  node_api["API request handling<br/>[api.ts]"]
  node_db[("PostgreSQL access<br/>[database.ts]")]
end

subgraph group_grades["Grade analytics"]
  node_imports["Grade import batches<br/>[server.ts]"]
  node_csv["CSV parsing<br/>[csv.ts]"]
  node_validation["Grade validation<br/>[grades.ts]"]
  node_rules["Zone rule sets<br/>[server.ts]"]
  node_classification["Zone classification<br/>[zones.ts]"]
  node_snapshots["Calculated snapshots<br/>[server.ts]"]
end

subgraph group_deliberation["Deliberation"]
  node_concerns["Concerns and referrals<br/>[server.ts]"]
  node_deliberationui["Deliberation screens"]
end

subgraph group_insights["Reporting and audit"]
  node_dashboard["Role dashboards<br/>[DashboardPage.tsx]"]
  node_results["Results and summaries<br/>[server.ts]"]
  node_dashboarddata["Dashboard data<br/>[dashboards.ts]"]
  node_reports["Reports and export<br/>[ReportsPage.tsx]"]
  node_audit["Audit log<br/>[audit.ts]"]
end

subgraph group_administration["Administration"]
  node_admin["User administration<br/>[server.ts]"]
end

node_staff(("Staff user"))
node_sis["SIS grade file"]

node_staff -->|"signs in"| node_login
node_login -->|"starts session"| node_auth
node_web -->|"checks access"| node_authorization
node_authorization -->|"loads identity"| node_auth
node_staff -.->|"uses"| node_web
node_staff -.->|"provides grades"| node_sis
node_sis -->|"uploads CSV"| node_imports
node_imports -->|"parses file"| node_csv
node_imports -->|"validates grades"| node_validation
node_imports -->|"stores batches"| node_db
node_staff -.->|"reviews batch"| node_imports
node_staff -.->|"configures rules"| node_rules
node_rules -->|"supplies thresholds"| node_classification
node_staff -.->|"requests calculation"| node_snapshots
node_snapshots -->|"writes results"| node_db
node_staff -->|"views dashboard"| node_dashboard
node_dashboard -->|"loads results"| node_results
node_dashboard -.->|"loads dashboard data"| node_dashboarddata
node_results -->|"queries snapshots"| node_db
node_staff -->|"views reports"| node_reports
node_reports -->|"loads report data"| node_results
node_staff -->|"reviews concerns"| node_deliberationui
node_deliberationui -->|"loads concerns"| node_concerns
node_concerns -->|"reads and updates"| node_db
node_staff -.->|"manages users"| node_admin
node_admin -->|"updates records"| node_db
node_auth -->|"reads sessions"| node_db
node_imports -->|"records actions"| node_audit
node_concerns -->|"records actions"| node_audit
node_admin -->|"records actions"| node_audit
node_audit -->|"writes log"| node_db

click node_web "https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/app/(protected)/layout.tsx"
click node_login "https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/components/LoginForm.tsx"
click node_auth "https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/auth.ts"
click node_authorization "https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/authorize.tsx"
click node_api "https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/api.ts"
click node_db "https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/database.ts"
click node_imports "https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/imports/server.ts"
click node_csv "https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/imports/csv.ts"
click node_validation "https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/imports/grades.ts"
click node_rules "https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/snapshots/server.ts"
click node_classification "https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/zones.ts"
click node_snapshots "https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/snapshots/server.ts"
click node_dashboard "https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/features/dashboard/DashboardPage.tsx"
click node_results "https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/results/server.ts"
click node_dashboarddata "https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/results/dashboards.ts"
click node_reports "https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/features/reports/ReportsPage.tsx"
click node_concerns "https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/concerns/server.ts"
click node_deliberationui "https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/features/deliberation/ConcernListPage.tsx"
click node_admin "https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/admin/server.ts"
click node_audit "https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/audit.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_login,node_auth,node_authorization,node_api,node_db,node_staff toneBlue
class node_imports,node_csv,node_validation,node_rules,node_classification,node_snapshots toneAmber
class node_concerns,node_deliberationui toneMint
class node_dashboard,node_results,node_dashboarddata,node_reports,node_audit toneRose
class node_admin,node_sis toneIndigo
```

## Components

### Access and platform

- [Web interface](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/app/(protected)/layout.tsx): `app/(protected)/layout.tsx`
- [Sign-in](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/components/LoginForm.tsx): `components/LoginForm.tsx`
- [Sessions and identity](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/auth.ts): `lib/auth.ts`
- [Role and scope checks](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/authorize.tsx): `lib/authorize.tsx`
- [API request handling](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/api.ts): `lib/api.ts`
- [PostgreSQL access](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/database.ts): `lib/database.ts`

### Grade analytics

- [Grade import batches](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/imports/server.ts): `lib/imports/server.ts`
- [CSV parsing](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/imports/csv.ts): `lib/imports/csv.ts`
- [Grade validation](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/imports/grades.ts): `lib/imports/grades.ts`
- [Zone rule sets](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/snapshots/server.ts): `lib/snapshots/server.ts`
- [Zone classification](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/zones.ts): `lib/zones.ts`
- [Calculated snapshots](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/snapshots/server.ts): `lib/snapshots/server.ts`

### Deliberation

- [Concerns and referrals](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/concerns/server.ts): `lib/concerns/server.ts`
- [Deliberation screens](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/features/deliberation/ConcernListPage.tsx): `features/deliberation/ConcernListPage.tsx`

### Reporting and audit

- [Role dashboards](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/features/dashboard/DashboardPage.tsx): `features/dashboard/DashboardPage.tsx`
- [Results and summaries](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/results/server.ts): `lib/results/server.ts`
- [Dashboard data](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/results/dashboards.ts): `lib/results/dashboards.ts`
- [Reports and export](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/features/reports/ReportsPage.tsx): `features/reports/ReportsPage.tsx`
- [Audit log](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/audit.ts): `lib/audit.ts`

### Administration

- [User administration](https://github.com/art-maker-blip/phinmaed-slc-analytics/blob/main/lib/admin/server.ts): `lib/admin/server.ts`

### Other components

- **Staff user**
- **SIS grade file**

## Connections

- Staff user → Sign-in: signs in
- Sign-in → Sessions and identity: starts session
- Web interface → Role and scope checks: checks access
- Role and scope checks → Sessions and identity: loads identity (evidence: `lib/authorize.tsx`)
- Staff user → Web interface: uses
- Staff user → SIS grade file: provides grades
- SIS grade file → Grade import batches: uploads CSV
- Grade import batches → CSV parsing: parses file (evidence: `lib/imports/server.ts`)
- Grade import batches → Grade validation: validates grades (evidence: `lib/imports/server.ts`)
- Grade import batches → PostgreSQL access: stores batches (evidence: `lib/imports/server.ts`)
- Staff user → Grade import batches: reviews batch
- Staff user → Zone rule sets: configures rules
- Zone rule sets → Zone classification: supplies thresholds (evidence: `lib/snapshots/server.ts`)
- Staff user → Calculated snapshots: requests calculation
- Calculated snapshots → PostgreSQL access: writes results (evidence: `lib/snapshots/server.ts`)
- Staff user → Role dashboards: views dashboard
- Role dashboards → Results and summaries: loads results (evidence: `app/(protected)/page.tsx`)
- Role dashboards → Dashboard data: loads dashboard data
- Results and summaries → PostgreSQL access: queries snapshots (evidence: `lib/results/server.ts`)
- Staff user → Reports and export: views reports
- Reports and export → Results and summaries: loads report data (evidence: `app/(protected)/reports/page.tsx`)
- Staff user → Deliberation screens: reviews concerns
- Deliberation screens → Concerns and referrals: loads concerns (evidence: `app/(protected)/deliberation/page.tsx`)
- Concerns and referrals → PostgreSQL access: reads and updates (evidence: `lib/concerns/server.ts`)
- Staff user → User administration: manages users
- User administration → PostgreSQL access: updates records (evidence: `lib/admin/server.ts`)
- Sessions and identity → PostgreSQL access: reads sessions (evidence: `lib/auth.ts`)
- Grade import batches → Audit log: records actions (evidence: `lib/imports/server.ts`)
- Concerns and referrals → Audit log: records actions (evidence: `lib/concerns/server.ts`)
- User administration → Audit log: records actions (evidence: `lib/admin/server.ts`)
- Audit log → PostgreSQL access: writes log (evidence: `lib/audit.ts`)