How vkonautomation/vkon_attendance works
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: pool.ts PostgreSQL · route.ts Punch route · punches.ts Punch service · app.js Employee portal
Components 23
Browser portal
- Employee portal
public/app.js - Admin console
public/admin.js - Browser rule engine
public/shared.js - Browser API adapter
public/js/api.js
Next.js API
- Authentication routes
app/api/auth/login/route.ts - Employee routes
app/api/employees/route.ts - Punch route
app/api/punches/route.ts - State routes
app/api/state/route.ts - Notification route
app/api/notify/route.ts - Session gate
lib/http/require-session.ts - Session management
lib/auth/session.ts
Attendance domain
- Roster service
lib/roster.ts - Punch service
lib/punches.ts - Attendance rules
lib/rules/index.ts - Attendance settings
lib/state/settings.ts - State documents
lib/state/documents.ts
Persistence and legacy backend
- PostgreSQL
lib/db/pool.ts - Audit writer
lib/db/audit.ts - Legacy FastAPI
server/api.py - Legacy policy
server/policy.py - Mail integration
lib/mail.ts
Other components
- Employee
- Administrator
Connections 26
- 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
app/api/auth/login/route.ts - Authentication routes → Session gate: uses
app/api/auth/login/route.ts - Employee routes → Session gate: authenticates
app/api/employees/route.ts - Employee routes → Roster service: reads and writes
app/api/employees/route.ts - Employee routes → Audit writer: records changes
app/api/employees/route.ts - Punch route → Session gate: authenticates
app/api/punches/route.ts - Punch route → Punch service: records punches
app/api/punches/route.ts - Punch route → Audit writer: records outcome
app/api/punches/route.ts - State routes → State documents: reads and writes
app/api/state/route.ts - Notification route → State documents: reads state
app/api/notify/route.ts - Notification route → Mail integration: sends notifications
app/api/notify/route.ts - Punch service → Attendance rules: uses attendance rules
lib/punches.ts - Punch service → Attendance settings: reads policy settings
lib/punches.ts - Roster service → PostgreSQL: queries employees
lib/roster.ts - Punch service → PostgreSQL: reads and writes
lib/punches.ts - State documents → PostgreSQL: reads and writes
lib/state/documents.ts - Audit writer → PostgreSQL: appends audit events
lib/db/audit.ts - Session management → PostgreSQL: queries sessions
lib/auth/session.ts - Legacy FastAPI → Legacy policy: uses policy
server/api.py - Legacy FastAPI → Employee portal: serves browser files