# voss-labs/verp architecture

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

- Interactive diagram: https://gitdiagram.com/voss-labs/verp
- Repository: https://github.com/voss-labs/verp

## Overview

VERP is a college ERP for student and faculty records, course offerings, marks, attendance, and departmental administration. Its principal workflow is VOSS sign-in, matching the verified identity to a roster record, then applying capability and record-scope checks before academic work is read or changed. The dashboard exposes role-specific operations; import preview and submission are distinct stages. The graph preserves documented academic, administrative, audit, and reporting areas. Evidence is limited to the README and sampled/indexed references; unsampled implementation links are omitted.

Main entry points: [`src/lib/session.ts`](https://github.com/voss-labs/verp/blob/main/src/lib/session.ts) (Identity binding), [`src/app/api/students/import/route.ts`](https://github.com/voss-labs/verp/blob/main/src/app/api/students/import/route.ts) (Roster import), [`src/app/api/marks/import/preview/route.ts`](https://github.com/voss-labs/verp/blob/main/src/app/api/marks/import/preview/route.ts) (Marks import preview), [`src/app/dashboard`](https://github.com/voss-labs/verp/tree/main/src/app/dashboard) (Role dashboards)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and access"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_session["Identity binding<br/>[session.ts]"]
  node_rbac["Capabilities and scope<br/>[rbac.ts]"]
end

subgraph group_academic["Academic operations"]
  node_dashboard["Role dashboards"]
  node_academic_pages["Class and marks pages"]
  node_student_import_preview["Roster import preview<br/>[route.ts]"]
  node_student_import["Roster import<br/>[route.ts]"]
  node_marks_preview["Marks import preview<br/>[route.ts]"]
  node_import_parsers["Import parsing<br/>[marks-import.ts]"]
  node_courses["Courses and offerings<br/>[courses.ts]"]
  node_attendance["Attendance tracking<br/>[attendance.ts]"]
  node_marks["Marks and results<br/>[marks.ts]"]
end

subgraph group_admin["Administration"]
  node_dept_actions["Department actions<br/>[actions.ts]"]
  node_admin_actions["Admin operations<br/>[actions.ts]"]
  node_audit["Audit records<br/>[audit.ts]"]
end

subgraph group_data["Persistence and reporting"]
  node_students["Student records<br/>[students.ts]"]
  node_import_batches["Import history<br/>[import-batches.ts]"]
  node_overview["Overview reporting<br/>[overview.ts]"]
  node_db[("Database<br/>[index.ts]")]
  node_schema["Academic schema"]
end

subgraph group_integrations["External services"]
  node_voss{{"VOSS identity"}}
end

node_staff_student(("College users"))

node_staff_student -->|"signs in"| node_voss
node_voss -->|"provides identity"| node_auth
node_auth -->|"resolves identity"| node_session
node_session -->|"resolves capabilities"| node_rbac
node_staff_student -->|"uses"| node_dashboard
node_dashboard -->|"invokes"| node_dept_actions
node_dashboard -->|"invokes"| node_admin_actions
node_dashboard -->|"shows"| node_academic_pages
node_student_import_preview -->|"checks access"| node_session
node_student_import -->|"checks access"| node_session
node_student_import -->|"checks capability"| node_rbac
node_student_import -->|"creates records"| node_students
node_student_import -->|"records batch"| node_import_batches
node_marks_preview -->|"checks access"| node_session
node_marks_preview -->|"checks capability"| node_rbac
node_marks_preview -->|"parses marks"| node_import_parsers
node_marks_preview -->|"matches roster"| node_students
node_dept_actions -->|"calls queries"| node_courses
node_dept_actions -->|"calls queries"| node_students
node_db -->|"configures ORM"| node_schema
node_overview -->|"queries"| node_db
node_overview -->|"reads records"| node_audit
node_staff_student -.->|"tracks attendance"| node_attendance
node_staff_student -.->|"enters and views"| node_marks
node_staff_student -.->|"reviews activity"| node_audit
node_staff_student -.->|"views summaries"| node_overview

click node_auth "https://github.com/voss-labs/verp/blob/main/src/lib/auth.ts"
click node_session "https://github.com/voss-labs/verp/blob/main/src/lib/session.ts"
click node_rbac "https://github.com/voss-labs/verp/blob/main/src/lib/rbac.ts"
click node_dashboard "https://github.com/voss-labs/verp/tree/main/src/app/dashboard"
click node_dept_actions "https://github.com/voss-labs/verp/blob/main/src/app/dashboard/dept/actions.ts"
click node_admin_actions "https://github.com/voss-labs/verp/blob/main/src/app/dashboard/admin/actions.ts"
click node_academic_pages "https://github.com/voss-labs/verp/tree/main/src/app/dashboard/class"
click node_student_import_preview "https://github.com/voss-labs/verp/blob/main/src/app/api/students/import/preview/route.ts"
click node_student_import "https://github.com/voss-labs/verp/blob/main/src/app/api/students/import/route.ts"
click node_marks_preview "https://github.com/voss-labs/verp/blob/main/src/app/api/marks/import/preview/route.ts"
click node_import_parsers "https://github.com/voss-labs/verp/blob/main/src/lib/marks-import.ts"
click node_students "https://github.com/voss-labs/verp/blob/main/src/db/queries/students.ts"
click node_import_batches "https://github.com/voss-labs/verp/blob/main/src/db/queries/import-batches.ts"
click node_courses "https://github.com/voss-labs/verp/blob/main/src/db/queries/courses.ts"
click node_attendance "https://github.com/voss-labs/verp/blob/main/src/db/queries/attendance.ts"
click node_marks "https://github.com/voss-labs/verp/blob/main/src/db/queries/marks.ts"
click node_audit "https://github.com/voss-labs/verp/blob/main/src/db/queries/audit.ts"
click node_overview "https://github.com/voss-labs/verp/blob/main/src/db/queries/overview.ts"
click node_db "https://github.com/voss-labs/verp/blob/main/src/db/index.ts"
click node_schema "https://github.com/voss-labs/verp/tree/main/src/db/schema"

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_auth,node_session,node_rbac,node_staff_student toneBlue
class node_dashboard,node_academic_pages,node_student_import_preview,node_student_import,node_marks_preview,node_import_parsers,node_courses,node_attendance,node_marks toneAmber
class node_dept_actions,node_admin_actions,node_audit toneMint
class node_students,node_import_batches,node_overview,node_db,node_schema toneRose
class node_voss toneIndigo
```

## Components

### Identity and access

- [Authentication](https://github.com/voss-labs/verp/blob/main/src/lib/auth.ts): `src/lib/auth.ts`
- [Identity binding](https://github.com/voss-labs/verp/blob/main/src/lib/session.ts): `src/lib/session.ts`
- [Capabilities and scope](https://github.com/voss-labs/verp/blob/main/src/lib/rbac.ts): `src/lib/rbac.ts`

### Academic operations

- [Role dashboards](https://github.com/voss-labs/verp/tree/main/src/app/dashboard): `src/app/dashboard`
- [Class and marks pages](https://github.com/voss-labs/verp/tree/main/src/app/dashboard/class): `src/app/dashboard/class`
- [Roster import preview](https://github.com/voss-labs/verp/blob/main/src/app/api/students/import/preview/route.ts): `src/app/api/students/import/preview/route.ts`
- [Roster import](https://github.com/voss-labs/verp/blob/main/src/app/api/students/import/route.ts): `src/app/api/students/import/route.ts`
- [Marks import preview](https://github.com/voss-labs/verp/blob/main/src/app/api/marks/import/preview/route.ts): `src/app/api/marks/import/preview/route.ts`
- [Import parsing](https://github.com/voss-labs/verp/blob/main/src/lib/marks-import.ts): `src/lib/marks-import.ts`
- [Courses and offerings](https://github.com/voss-labs/verp/blob/main/src/db/queries/courses.ts): `src/db/queries/courses.ts`
- [Attendance tracking](https://github.com/voss-labs/verp/blob/main/src/db/queries/attendance.ts): `src/db/queries/attendance.ts`
- [Marks and results](https://github.com/voss-labs/verp/blob/main/src/db/queries/marks.ts): `src/db/queries/marks.ts`

### Administration

- [Department actions](https://github.com/voss-labs/verp/blob/main/src/app/dashboard/dept/actions.ts): `src/app/dashboard/dept/actions.ts`
- [Admin operations](https://github.com/voss-labs/verp/blob/main/src/app/dashboard/admin/actions.ts): `src/app/dashboard/admin/actions.ts`
- [Audit records](https://github.com/voss-labs/verp/blob/main/src/db/queries/audit.ts): `src/db/queries/audit.ts`

### Persistence and reporting

- [Student records](https://github.com/voss-labs/verp/blob/main/src/db/queries/students.ts): `src/db/queries/students.ts`
- [Import history](https://github.com/voss-labs/verp/blob/main/src/db/queries/import-batches.ts): `src/db/queries/import-batches.ts`
- [Overview reporting](https://github.com/voss-labs/verp/blob/main/src/db/queries/overview.ts): `src/db/queries/overview.ts`
- [Database](https://github.com/voss-labs/verp/blob/main/src/db/index.ts): `src/db/index.ts`
- [Academic schema](https://github.com/voss-labs/verp/tree/main/src/db/schema): `src/db/schema`

### External services

- **VOSS identity**

### Other components

- **College users**

## Connections

- College users → VOSS identity: signs in
- VOSS identity → Authentication: provides identity
- Authentication → Identity binding: resolves identity (evidence: `src/lib/session.ts`)
- Identity binding → Capabilities and scope: resolves capabilities (evidence: `src/lib/session.ts`)
- College users → Role dashboards: uses
- Role dashboards → Department actions: invokes (evidence: `src/app/dashboard/dept/client.tsx`)
- Role dashboards → Admin operations: invokes (evidence: `src/app/dashboard/admin/departments/client.tsx`)
- Role dashboards → Class and marks pages: shows
- Roster import preview → Identity binding: checks access (evidence: `src/app/api/students/import/preview/route.ts`)
- Roster import → Identity binding: checks access (evidence: `src/app/api/students/import/route.ts`)
- Roster import → Capabilities and scope: checks capability (evidence: `src/app/api/students/import/route.ts`)
- Roster import → Student records: creates records (evidence: `src/app/api/students/import/route.ts`)
- Roster import → Import history: records batch (evidence: `src/app/api/students/import/route.ts`)
- Marks import preview → Identity binding: checks access (evidence: `src/app/api/marks/import/preview/route.ts`)
- Marks import preview → Capabilities and scope: checks capability (evidence: `src/app/api/marks/import/preview/route.ts`)
- Marks import preview → Import parsing: parses marks (evidence: `src/app/api/marks/import/preview/route.ts`)
- Marks import preview → Student records: matches roster (evidence: `src/app/api/marks/import/preview/route.ts`)
- Department actions → Courses and offerings: calls queries (evidence: `src/app/dashboard/dept/actions.ts`)
- Department actions → Student records: calls queries (evidence: `src/app/dashboard/dept/actions.ts`)
- Database → Academic schema: configures ORM (evidence: `src/db/index.ts`)
- Overview reporting → Database: queries (evidence: `src/db/queries/overview.ts`)
- Overview reporting → Audit records: reads records (evidence: `src/db/queries/overview.ts`)
- College users → Attendance tracking: tracks attendance
- College users → Marks and results: enters and views
- College users → Audit records: reviews activity
- College users → Overview reporting: views summaries
