# oliver-ostojic/logbook-writer architecture

> Architecture diagram of the GitHub repository oliver-ostojic/logbook-writer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oliver-ostojic/logbook-writer
- Repository: https://github.com/oliver-ostojic/logbook-writer

## Overview

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: [`apps/api`](https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/api) (API), [`apps/api/src/routes`](https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/api/src/routes) (API routes), [`apps/api/src/services`](https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/api/src/services) (Schedule pipeline), [`apps/solver-python`](https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/solver-python) (Python solver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Apps"]
  node_web["Web app<br/>Next.js UI"]
  node_api["API<br/>Fastify backend"]
  node_solverpy["Python solver<br/>solver research"]
  node_ml["ML support<br/>auxiliary ML"]
  node_db[("Prisma DB<br/>persistence")]
  node_routes["API routes<br/>REST surface"]
  node_pipeline{{"Schedule pipeline<br/>staged assembly"}}
  node_segmentation["Segmentation<br/>shift partitioning<br/>[segmentation.ts]"]
  node_logbooks["Logbook manager<br/>publication flow<br/>[logbook-manager.ts]"]
  node_analytics["Dashboard service<br/>fairness analytics"]
  node_pdf["PDF output<br/>report generation<br/>[pdf-generator.ts]"]
  node_rbac["RBAC middleware<br/>access control<br/>[rbac.ts]"]
  node_activity["Activity logging<br/>audit trail<br/>[activity-logger.ts]"]
  node_dashui["Fairness dashboard<br/>UI analytics"]
  node_webhooks["API hooks<br/>data access"]
  node_shell["Layout shell<br/>UI scaffolding"]
  node_schedule2{{"Solver2 engine<br/>MILP builder"}}
  node_tuning{{"Tuning engine<br/>search/metrics"}}
end

subgraph group_packages["Packages"]
  node_domain["Domain rules<br/>shared core"]
  node_types["Shared types<br/>DTO contracts"]
end

subgraph group_infra["Infra"]
end

node_web -->|"fetches"| node_webhooks
node_web -->|"uses"| node_shell
node_dashui -->|"loads"| node_webhooks
node_api -->|"exposes"| node_routes
node_routes -->|"guards"| node_rbac
node_routes -->|"logs"| node_activity
node_api -->|"persists"| node_db
node_api -->|"orchestrates"| node_pipeline
node_pipeline -->|"splits"| node_segmentation
node_pipeline -->|"assembles input"| node_schedule2
node_api -->|"publishes"| node_logbooks
node_logbooks -->|"renders"| node_pdf
node_api -->|"serves metrics"| node_analytics
node_analytics -->|"reads history"| node_db
node_api -->|"uses"| node_domain
node_schedule2 -->|"relies on"| node_domain
node_solverpy -->|"mirrors"| node_domain
node_solverpy -->|"contains"| node_tuning
node_webhooks -->|"shares contracts"| node_types
node_api -->|"emits contracts"| node_types
node_db -->|"feeds"| node_schedule2
node_ml -.->|"supports"| node_solverpy

click node_web "https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/web"
click node_api "https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/api"
click node_solverpy "https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/solver-python"
click node_ml "https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/ml"
click node_domain "https://github.com/oliver-ostojic/logbook-writer/tree/main/packages/domain"
click node_types "https://github.com/oliver-ostojic/logbook-writer/tree/main/packages/shared-types"
click node_db "https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/api/prisma"
click node_routes "https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/api/src/routes"
click node_pipeline "https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/api/src/services"
click node_segmentation "https://github.com/oliver-ostojic/logbook-writer/blob/main/apps/api/src/services/segmentation.ts"
click node_logbooks "https://github.com/oliver-ostojic/logbook-writer/blob/main/apps/api/src/services/logbook-manager.ts"
click node_analytics "https://github.com/oliver-ostojic/logbook-writer/blob/main/apps/api/src/services/dashboard.service.ts"
click node_pdf "https://github.com/oliver-ostojic/logbook-writer/blob/main/apps/api/src/services/pdf-generator.ts"
click node_rbac "https://github.com/oliver-ostojic/logbook-writer/blob/main/apps/api/src/middleware/rbac.ts"
click node_activity "https://github.com/oliver-ostojic/logbook-writer/blob/main/apps/api/src/services/activity-logger.ts"
click node_dashui "https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/web/src/dashboard"
click node_webhooks "https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/web/lib/api"
click node_shell "https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/web/components/layouts"
click node_schedule2 "https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/api/src/solver2"
click node_tuning "https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/solver-python/tuning_engine"

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_web,node_api,node_solverpy,node_ml,node_db,node_routes,node_pipeline,node_segmentation,node_logbooks,node_analytics,node_pdf,node_rbac,node_activity,node_dashui,node_webhooks,node_shell,node_schedule2,node_tuning toneBlue
class node_domain,node_types toneAmber
```

## Components

### Apps

Deployable runtimes and user-facing services.

- [Web app](https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/web): Next.js UI · Store-centric console for admin, logbook creation, and fairness views. · `apps/web`
- [API](https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/api): Fastify backend · System of record and orchestration layer for schedule workflows. · `apps/api`
- [Python solver](https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/solver-python): solver research · Standalone solver, tuning, diagnostics, and benchmark experiments. · `apps/solver-python`
- [ML support](https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/ml): auxiliary ML · Smaller machine-learning area adjacent to scheduling and tuning. · `apps/ml`
- [Prisma DB](https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/api/prisma): persistence · Models and migrations for stores, crew, rules, logbooks, runs, and fairness state. · `apps/api/prisma`
- [API routes](https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/api/src/routes): REST surface · Auth, crew, stores, constraints, schedule, runs, tuning, dashboards, and solver input endpoints. · `apps/api/src/routes`
- [Schedule pipeline](https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/api/src/services): staged assembly · Wizard, normalization, coverage upserts, segmentation, and solver-input preparation. · `apps/api/src/services`
- [Segmentation](https://github.com/oliver-ostojic/logbook-writer/blob/main/apps/api/src/services/segmentation.ts): shift partitioning · Splits shifts into PRODUCT and FLEX regions using store defaults. · `apps/api/src/services/segmentation.ts`
- [Logbook manager](https://github.com/oliver-ostojic/logbook-writer/blob/main/apps/api/src/services/logbook-manager.ts): publication flow · Builds, stores, and publishes daily logbooks and historical artifacts. · `apps/api/src/services/logbook-manager.ts`
- [Dashboard service](https://github.com/oliver-ostojic/logbook-writer/blob/main/apps/api/src/services/dashboard.service.ts): fairness analytics · Computes snapshots, rollups, and analytics backing dashboard views. · `apps/api/src/services/dashboard.service.ts`
- [PDF output](https://github.com/oliver-ostojic/logbook-writer/blob/main/apps/api/src/services/pdf-generator.ts): report generation · Produces printable logbook artifacts for published schedules. · `apps/api/src/services/pdf-generator.ts`
- [RBAC middleware](https://github.com/oliver-ostojic/logbook-writer/blob/main/apps/api/src/middleware/rbac.ts): access control · Role-based authorization guard for protected API operations. · `apps/api/src/middleware/rbac.ts`
- [Activity logging](https://github.com/oliver-ostojic/logbook-writer/blob/main/apps/api/src/services/activity-logger.ts): audit trail · Records user and system actions for operational traceability. · `apps/api/src/services/activity-logger.ts`
- [Fairness dashboard](https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/web/src/dashboard): UI analytics · Client-side fairness and logbook analytics views in the web app. · `apps/web/src/dashboard`
- [API hooks](https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/web/lib/api): data access · Network boundary for auth and dashboard/store data fetching in the web app. · `apps/web/lib/api`
- [Layout shell](https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/web/components/layouts): UI scaffolding · Shared providers, auth protection, and dashboard shell/navigation. · `apps/web/components/layouts`
- [Solver2 engine](https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/api/src/solver2): MILP builder · Node-side solver input builder and constraint appliers used by the API. · `apps/api/src/solver2`
- [Tuning engine](https://github.com/oliver-ostojic/logbook-writer/tree/main/apps/solver-python/tuning_engine): search/metrics · 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](https://github.com/oliver-ostojic/logbook-writer/tree/main/packages/domain): shared core · Normalization, validation, scoring, and solve helpers for scheduling correctness. · `packages/domain`
- [Shared types](https://github.com/oliver-ostojic/logbook-writer/tree/main/packages/shared-types): DTO contracts · Shared API/UI contracts to keep data shapes aligned. · `packages/shared-types`

## Connections

- 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.
