An invariant-first, append-only domain system for accurately representing real-world work time, paired with a worker-facing application for transit operations.
Transit Business Time Ledger is a full-stack system designed for workers in a transit business to reliably record, review, and understand their work life.
At its core, the system prioritizes truth, auditability, and correctness over convenience.
The backend models reality as it happened. The frontend allows workers to interact with that reality safely and clearly.
Most time-tracking systems assume that planned schedules equal reality. In real transit operations, this assumption breaks down quickly.
Workers:
- start late or early
- take over shifts
- work overtime unexpectedly
- record data hours or days later
- occasionally make mistakes when entering times
Traditional systems handle this by editing records, which silently rewrites history and destroys trust.
This project takes a different approach.
Reality is never edited. Mistakes are corrected, not erased.
The system is built around a few strict principles:
- Reality is append-only
- Corrections explain mistakes
- Effective truth is computed
- Planning never overrides reality
- Invariants over convenience
- A worker-facing work-life tracking system
- Designed for transit businesses and their operators
- Focused on what actually happened
- Built using domain-driven design principles
- A payroll system
- A scheduling authority
- A compliance or HR system
domain/ → Pure business logic & invariants
application/ → Use-case orchestration
ports/ → Repository & policy interfaces
infrastructure → Prisma + PostgreSQL implementations
interfaces/ → HTTP controllers & middleware
tests/ → Invariant and lifecycle tests
Backend:
- Node.js
- TypeScript
- PostgreSQL
- Prisma ORM
- Express
- Jest
- Docker
Frontend (planned):
- Worker-facing web/mobile app
- Node.js 18+
- Docker
- npm
git clone https://github.com/your-username/transit-business-time-ledger.git cd transit-business-time-ledger npm install cp .env.example .env
docker compose up -d
npx prisma migrate dev npx prisma generate
npm run dev
Server runs on http://localhost:3000
npm test
- Backend domain model: complete
- Invariants: locked
- Domain APIs: finalized
- Infrastructure & HTTP layers: in progress
- Frontend application: planned
This system intentionally avoids shortcuts.
Start with the domain invariants, then the correction model, then the effective time rules.