How oliver-ostojic/logbook-writer works
1. This repository is a monorepo for a logbook/schedule generation system. The central business flow is: ingest crew shifts, store rules, and preferences; normalize and segment them; compute or prepare a solver input; then publish a daily logbook plus fairness/coverage analytics.
2. The architecture is split into four main product boundaries:
- apps/api: Fastify + Prisma backend and the main system of record.
- apps/web: Next.js UI for admin, store operations, logbook creation, and fairness views.
- packages/domain: shared domain rules for normalization, validation, constraint scoring, and solving helpers.
- packages/shared-types: shared DTO/type definitions to keep API and web aligned.
3. apps/api is the orchestration layer. It owns REST endpoints for auth, crew, roles, stores, constraints, schedule, runs, tuning, and dashboards. It also owns persistence via Prisma against PostgreSQL, and includes RBAC middleware plus activity logging.
4. The schedule pipeline in the API is staged rather than monolithic. Wizard endpoints normalize dates and load/store inputs, coverage and requirements are upserted separately, shift segmentation splits shifts into PRODUCT vs FLEX regions using store register-window defaults, and /schedule/run assembles a complete engine input. The current readme indicates the solver output is still partially stubbed/debug-oriented, so the “engine integration” boundary is explicit.
5. packages/domain is the rule engine’s shared core. It contains validators for availability, qualification, overlap, daily hours, store hours, window coverage, slot alignment, break policy, and role-slot duration, plus scorers for favorite, timing, first-hour, and consecutive preferences. This package is the main correctness boundary used by tests and likely by both API and solver code.
6. Persistence is centered on Prisma models and migrations in apps/api/prisma. The schema captures stores, crew, roles, constraints, logbooks, runs, fairness trackers, and historical records. A notable architectural decision is calendar-date storage using @db.Date plus UTC normalization to avoid timezone drift in daily schedule semantics.
7. The web application is a store-centric console built with the Next.js app router. Major user flows live under app/stores/[storeId]: home/admin CRUD, fairness dashboards, logbook creation, settings, and crew detail pages. The UI is split into many feature components, but they all depend on API-backed data hooks and shared dashboard/layout primitives.
8. The web app’s data boundary is deliberate: lib/api and hooks like useDashboardData, useStoreInfo, and useAvailableDates isolate network access; components/providers wrap auth and query state; components/layouts handle shared shell/navigation. This keeps UI concerns separated from schedule/fairness computation.
9. The fairness dashboard is a distinct analytics subsystem. apps/web/src/dashboard computes snapshots and metrics such as Lorenz curves, bucket distributions, logbook stats, and role/crew rollups. The API exposes a dashboard route, while the UI renders charts, heatmaps, box plots, and per-crew/per-role drilldowns from these computed metrics.
10. Solver experimentation is split out into Python in apps/solver-python. That area contains a standalone solver, a v2 logbook solver, tuning engines, benchmark inputs/outputs, diagnostics, and ML-assisted oracle tooling. This is a separate compute boundary from the Node API and appears to be used for research, performance testing, and solver-quality tuning rather than day-to-day UI rendering.
11. There is also a smaller apps/ml area, but the dominant machine-learning-related work appears to live in the Python solver/tuning stack. In the current repo layout, ML is auxiliary to scheduling rather than the primary application runtime.
12. Operationally, the repo uses Turborepo and pnpm workspaces, with GitHub Actions for CI and API tests. Docker assets (Dockerfile, Dockerfile.web, infra/docker-compose.yml, railway.toml) show the system is intended to run as separate deployable services with a shared database, not as a single binary.
13. The codebase has strong migration and data-massage support: many scripts in apps/api/prisma and apps/api/scripts handle backfills, schema evolution, fairness recalculation, role-rule migration, and solver-input inspection. That suggests the architecture must tolerate evolving scheduling rules and historical data corrections.
14. For an architecture diagram, the key data flow is:
user/UI in apps/web -> authenticated API calls to apps/api -> Prisma/PostgreSQL persistence -> domain normalization/validation/segmentation -> solver input preparation or Python solver runs -> logbook/fairness artifacts -> web dashboards, PDFs, and history views.
15. The most important boundary to show is between “system of record and orchestration” (apps/api + database) and “pure rules/analytics/solver computation” (packages/domain, Python solver, dashboard metrics). The web app is mainly a consumer/editor of that state, while the solver and domain packages define the scheduling intelligence.
Main entry points: api API · routes API routes · services Schedule pipeline · solver-python Python solver
Components 20
Apps
Deployable runtimes and user-facing services.
- Web app · Store-centric console for admin, logbook creation, and fairness views.
apps/web - API · System of record and orchestration layer for schedule workflows.
apps/api - Python solver · Standalone solver, tuning, diagnostics, and benchmark experiments.
apps/solver-python - ML support · Smaller machine-learning area adjacent to scheduling and tuning.
apps/ml - Prisma DB · Models and migrations for stores, crew, rules, logbooks, runs, and fairness state.
apps/api/prisma - API routes · Auth, crew, stores, constraints, schedule, runs, tuning, dashboards, and solver input endpoints.
apps/api/src/routes - Schedule pipeline · Wizard, normalization, coverage upserts, segmentation, and solver-input preparation.
apps/api/src/services - Segmentation · Splits shifts into PRODUCT and FLEX regions using store defaults.
apps/api/src/services/segmentation.ts - Logbook manager · Builds, stores, and publishes daily logbooks and historical artifacts.
apps/api/src/services/logbook-manager.ts - Dashboard service · Computes snapshots, rollups, and analytics backing dashboard views.
apps/api/src/services/dashboard.service.ts - PDF output · Produces printable logbook artifacts for published schedules.
apps/api/src/services/pdf-generator.ts - RBAC middleware · Role-based authorization guard for protected API operations.
apps/api/src/middleware/rbac.ts - Activity logging · Records user and system actions for operational traceability.
apps/api/src/services/activity-logger.ts - Fairness dashboard · Client-side fairness and logbook analytics views in the web app.
apps/web/src/dashboard - API hooks · Network boundary for auth and dashboard/store data fetching in the web app.
apps/web/lib/api - Layout shell · Shared providers, auth protection, and dashboard shell/navigation.
apps/web/components/layouts - Solver2 engine · Node-side solver input builder and constraint appliers used by the API.
apps/api/src/solver2 - Tuning engine · Python optimization loop for conflict resolution, equalization, and satisfaction tuning.
apps/solver-python/tuning_engine
Packages
Shared rule and type libraries used across runtimes.
- Domain rules · Normalization, validation, scoring, and solve helpers for scheduling correctness.
packages/domain - Shared types · Shared API/UI contracts to keep data shapes aligned.
packages/shared-types
Connections 22
- Web app → API hooks: fetches · UI reads and mutates state through authenticated API helpers.
- Web app → Layout shell: uses · Pages share auth providers and dashboard layout primitives.
- Fairness dashboard → API hooks: loads · Fairness screens consume store and dashboard data from the API.
- API → API routes: exposes · Primary REST surface for the application.
- API routes → RBAC middleware: guards · Protected endpoints apply authorization checks.
- API routes → Activity logging: logs · Mutations and important actions are audited.
- API → Prisma DB: persists · Prisma models and migrations back system-of-record state.
- API → Schedule pipeline: orchestrates · API stages schedule creation and normalization workflows.
- Schedule pipeline → Segmentation: splits · Shift regions are partitioned before solver input assembly.
- Schedule pipeline → Solver2 engine: assembles input · Prepared data is transformed into engine-ready solver input.
- API → Logbook manager: publishes · Logbook creation and history management live in the API layer.
- Logbook manager → PDF output: renders · Published logbooks can be emitted as PDFs.
- API → Dashboard service: serves metrics · Dashboard route exposes fairness and coverage analytics.
- Dashboard service → Prisma DB: reads history · Metrics are derived from persisted runs, logbooks, and tracker state.
- API → Domain rules: uses · Normalization, validation, scoring, and solver helpers are shared core logic.
- Solver2 engine → Domain rules: relies on · Solver2 uses shared constraint and normalization rules.
- Python solver → Domain rules: mirrors · Python solver stack aligns with shared scheduling semantics.
- Python solver → Tuning engine: contains · Tuning engine is a major sub-bounded compute pipeline.
- API hooks → Shared types: shares contracts · Frontend and backend agree on DTO shapes through shared types.
- API → Shared types: emits contracts · API payloads are aligned with shared type definitions.
- Prisma DB → Solver2 engine: feeds · Persisted rules and shifts become solver inputs.
- ML support → Python solver: supports · Auxiliary ML work sits beside the Python solver experimentation stack.