# vkonautomation/vkon_attendance architecture

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

- Interactive diagram: https://gitdiagram.com/vkonautomation/vkon_attendance
- Repository: https://github.com/vkonautomation/vkon_attendance

## Overview

Vkon is an employee attendance and verification platform: employees sign in, record punches, and view attendance; administrators and managers handle roster and attendance workflows. The README describes both a legacy FastAPI backend, which production still runs, and a Next.js API intended to take over. The browser currently hydrates from public-side storage; the state-document facade exists in the repository but is not yet the shipped portal data path. Relationships below follow the README and indexed or excerpted source references; unsampled implementation details are not assumed.

Main entry points: [`lib/db/pool.ts`](https://github.com/vkonautomation/vkon_attendance/blob/main/lib/db/pool.ts) (PostgreSQL), [`app/api/punches/route.ts`](https://github.com/vkonautomation/vkon_attendance/blob/main/app/api/punches/route.ts) (Punch route), [`lib/punches.ts`](https://github.com/vkonautomation/vkon_attendance/blob/main/lib/punches.ts) (Punch service), [`public/app.js`](https://github.com/vkonautomation/vkon_attendance/blob/main/public/app.js) (Employee portal)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser portal"]
  node_portal["Employee portal<br/>[app.js]"]
  node_console["Admin console<br/>[admin.js]"]
  node_browser_rules["Browser rule engine<br/>[shared.js]"]
  node_browser_api["Browser API adapter<br/>[api.js]"]
end

subgraph group_next["Next.js API"]
  node_auth_routes["Authentication routes<br/>[route.ts]"]
  node_roster_route["Employee routes<br/>[route.ts]"]
  node_punch_route["Punch route<br/>[route.ts]"]
  node_state_routes["State routes<br/>[route.ts]"]
  node_notify_route["Notification route<br/>[route.ts]"]
  node_session_gate["Session gate<br/>[require-session.ts]"]
  node_auth_sessions["Session management<br/>[session.ts]"]
end

subgraph group_domain["Attendance domain"]
  node_roster["Roster service<br/>[roster.ts]"]
  node_punches["Punch service<br/>[punches.ts]"]
  node_rules["Attendance rules<br/>[index.ts]"]
  node_settings["Attendance settings<br/>[settings.ts]"]
  node_documents["State documents<br/>[documents.ts]"]
end

subgraph group_storage["Persistence and legacy backend"]
  node_database[("PostgreSQL<br/>[pool.ts]")]
  node_audit["Audit writer<br/>[audit.ts]"]
  node_legacy_api["Legacy FastAPI<br/>[api.py]"]
  node_legacy_policy["Legacy policy<br/>[policy.py]"]
  node_mail["Mail integration<br/>[mail.ts]"]
end

node_employee(("Employee"))
node_administrator(("Administrator"))

node_employee -->|"uses"| node_portal
node_administrator -->|"uses"| node_console
node_portal -->|"uses"| node_browser_rules
node_console -->|"uses"| node_browser_rules
node_portal -->|"requests data"| node_browser_api
node_browser_api -->|"submits punches"| node_punch_route
node_auth_routes -->|"manages sessions"| node_auth_sessions
node_auth_routes -->|"uses"| node_session_gate
node_roster_route -->|"authenticates"| node_session_gate
node_roster_route -->|"reads and writes"| node_roster
node_roster_route -->|"records changes"| node_audit
node_punch_route -->|"authenticates"| node_session_gate
node_punch_route -->|"records punches"| node_punches
node_punch_route -->|"records outcome"| node_audit
node_state_routes -->|"reads and writes"| node_documents
node_notify_route -->|"reads state"| node_documents
node_notify_route -->|"sends notifications"| node_mail
node_punches -->|"uses attendance rules"| node_rules
node_punches -->|"reads policy settings"| node_settings
node_roster -->|"queries employees"| node_database
node_punches -->|"reads and writes"| node_database
node_documents -->|"reads and writes"| node_database
node_audit -->|"appends audit events"| node_database
node_auth_sessions -->|"queries sessions"| node_database
node_legacy_api -->|"uses policy"| node_legacy_policy
node_legacy_api -->|"serves browser files"| node_portal

click node_portal "https://github.com/vkonautomation/vkon_attendance/blob/main/public/app.js"
click node_console "https://github.com/vkonautomation/vkon_attendance/blob/main/public/admin.js"
click node_browser_rules "https://github.com/vkonautomation/vkon_attendance/blob/main/public/shared.js"
click node_browser_api "https://github.com/vkonautomation/vkon_attendance/blob/main/public/js/api.js"
click node_auth_routes "https://github.com/vkonautomation/vkon_attendance/blob/main/app/api/auth/login/route.ts"
click node_roster_route "https://github.com/vkonautomation/vkon_attendance/blob/main/app/api/employees/route.ts"
click node_punch_route "https://github.com/vkonautomation/vkon_attendance/blob/main/app/api/punches/route.ts"
click node_state_routes "https://github.com/vkonautomation/vkon_attendance/blob/main/app/api/state/route.ts"
click node_notify_route "https://github.com/vkonautomation/vkon_attendance/blob/main/app/api/notify/route.ts"
click node_session_gate "https://github.com/vkonautomation/vkon_attendance/blob/main/lib/http/require-session.ts"
click node_auth_sessions "https://github.com/vkonautomation/vkon_attendance/blob/main/lib/auth/session.ts"
click node_roster "https://github.com/vkonautomation/vkon_attendance/blob/main/lib/roster.ts"
click node_punches "https://github.com/vkonautomation/vkon_attendance/blob/main/lib/punches.ts"
click node_rules "https://github.com/vkonautomation/vkon_attendance/blob/main/lib/rules/index.ts"
click node_settings "https://github.com/vkonautomation/vkon_attendance/blob/main/lib/state/settings.ts"
click node_documents "https://github.com/vkonautomation/vkon_attendance/blob/main/lib/state/documents.ts"
click node_database "https://github.com/vkonautomation/vkon_attendance/blob/main/lib/db/pool.ts"
click node_audit "https://github.com/vkonautomation/vkon_attendance/blob/main/lib/db/audit.ts"
click node_legacy_api "https://github.com/vkonautomation/vkon_attendance/blob/main/server/api.py"
click node_legacy_policy "https://github.com/vkonautomation/vkon_attendance/blob/main/server/policy.py"
click node_mail "https://github.com/vkonautomation/vkon_attendance/blob/main/lib/mail.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_portal,node_console,node_browser_rules,node_browser_api toneBlue
class node_auth_routes,node_roster_route,node_punch_route,node_state_routes,node_notify_route,node_session_gate,node_auth_sessions toneAmber
class node_roster,node_punches,node_rules,node_settings,node_documents toneMint
class node_database,node_audit,node_legacy_api,node_legacy_policy,node_mail toneRose
class node_employee,node_administrator toneIndigo
```

## Components

### Browser portal

- [Employee portal](https://github.com/vkonautomation/vkon_attendance/blob/main/public/app.js): `public/app.js`
- [Admin console](https://github.com/vkonautomation/vkon_attendance/blob/main/public/admin.js): `public/admin.js`
- [Browser rule engine](https://github.com/vkonautomation/vkon_attendance/blob/main/public/shared.js): `public/shared.js`
- [Browser API adapter](https://github.com/vkonautomation/vkon_attendance/blob/main/public/js/api.js): `public/js/api.js`

### Next.js API

- [Authentication routes](https://github.com/vkonautomation/vkon_attendance/blob/main/app/api/auth/login/route.ts): `app/api/auth/login/route.ts`
- [Employee routes](https://github.com/vkonautomation/vkon_attendance/blob/main/app/api/employees/route.ts): `app/api/employees/route.ts`
- [Punch route](https://github.com/vkonautomation/vkon_attendance/blob/main/app/api/punches/route.ts): `app/api/punches/route.ts`
- [State routes](https://github.com/vkonautomation/vkon_attendance/blob/main/app/api/state/route.ts): `app/api/state/route.ts`
- [Notification route](https://github.com/vkonautomation/vkon_attendance/blob/main/app/api/notify/route.ts): `app/api/notify/route.ts`
- [Session gate](https://github.com/vkonautomation/vkon_attendance/blob/main/lib/http/require-session.ts): `lib/http/require-session.ts`
- [Session management](https://github.com/vkonautomation/vkon_attendance/blob/main/lib/auth/session.ts): `lib/auth/session.ts`

### Attendance domain

- [Roster service](https://github.com/vkonautomation/vkon_attendance/blob/main/lib/roster.ts): `lib/roster.ts`
- [Punch service](https://github.com/vkonautomation/vkon_attendance/blob/main/lib/punches.ts): `lib/punches.ts`
- [Attendance rules](https://github.com/vkonautomation/vkon_attendance/blob/main/lib/rules/index.ts): `lib/rules/index.ts`
- [Attendance settings](https://github.com/vkonautomation/vkon_attendance/blob/main/lib/state/settings.ts): `lib/state/settings.ts`
- [State documents](https://github.com/vkonautomation/vkon_attendance/blob/main/lib/state/documents.ts): `lib/state/documents.ts`

### Persistence and legacy backend

- [PostgreSQL](https://github.com/vkonautomation/vkon_attendance/blob/main/lib/db/pool.ts): `lib/db/pool.ts`
- [Audit writer](https://github.com/vkonautomation/vkon_attendance/blob/main/lib/db/audit.ts): `lib/db/audit.ts`
- [Legacy FastAPI](https://github.com/vkonautomation/vkon_attendance/blob/main/server/api.py): `server/api.py`
- [Legacy policy](https://github.com/vkonautomation/vkon_attendance/blob/main/server/policy.py): `server/policy.py`
- [Mail integration](https://github.com/vkonautomation/vkon_attendance/blob/main/lib/mail.ts): `lib/mail.ts`

### Other components

- **Employee**
- **Administrator**

## Connections

- Employee → Employee portal: uses
- Administrator → Admin console: uses
- Employee portal → Browser rule engine: uses
- Admin console → Browser rule engine: uses
- Employee portal → Browser API adapter: requests data
- Browser API adapter → Punch route: submits punches
- Authentication routes → Session management: manages sessions (evidence: `app/api/auth/login/route.ts`)
- Authentication routes → Session gate: uses (evidence: `app/api/auth/login/route.ts`)
- Employee routes → Session gate: authenticates (evidence: `app/api/employees/route.ts`)
- Employee routes → Roster service: reads and writes (evidence: `app/api/employees/route.ts`)
- Employee routes → Audit writer: records changes (evidence: `app/api/employees/route.ts`)
- Punch route → Session gate: authenticates (evidence: `app/api/punches/route.ts`)
- Punch route → Punch service: records punches (evidence: `app/api/punches/route.ts`)
- Punch route → Audit writer: records outcome (evidence: `app/api/punches/route.ts`)
- State routes → State documents: reads and writes (evidence: `app/api/state/route.ts`)
- Notification route → State documents: reads state (evidence: `app/api/notify/route.ts`)
- Notification route → Mail integration: sends notifications (evidence: `app/api/notify/route.ts`)
- Punch service → Attendance rules: uses attendance rules (evidence: `lib/punches.ts`)
- Punch service → Attendance settings: reads policy settings (evidence: `lib/punches.ts`)
- Roster service → PostgreSQL: queries employees (evidence: `lib/roster.ts`)
- Punch service → PostgreSQL: reads and writes (evidence: `lib/punches.ts`)
- State documents → PostgreSQL: reads and writes (evidence: `lib/state/documents.ts`)
- Audit writer → PostgreSQL: appends audit events (evidence: `lib/db/audit.ts`)
- Session management → PostgreSQL: queries sessions (evidence: `lib/auth/session.ts`)
- Legacy FastAPI → Legacy policy: uses policy (evidence: `server/api.py`)
- Legacy FastAPI → Employee portal: serves browser files
