# itaykapon1-lab/shiftapp-release architecture

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

- Interactive diagram: https://gitdiagram.com/itaykapon1-lab/shiftapp-release
- Repository: https://github.com/itaykapon1-lab/shiftapp-release

## Overview

ShiftApp is an employee-scheduling product: managers enter workers, shifts, and rules in a React interface, then request and review optimized weekly schedules. The backend exposes CRUD, constraint, solver, and Excel workflows; its solver builds a MILP and can diagnose infeasibility asynchronously. The graph preserves the documented Excel and onboarding capabilities. Some route, job-store, and frontend details are unsampled, so uncertain connections are omitted or shown as unverified.

Main entry points: [`api/routes.py`](https://github.com/itaykapon1-lab/shiftapp-release/blob/main/api/routes.py) (API router hub), [`frontend/src/App.jsx`](https://github.com/itaykapon1-lab/shiftapp-release/blob/main/frontend/src/App.jsx) (Scheduling UI), [`repositories/sql_repo.py`](https://github.com/itaykapon1-lab/shiftapp-release/blob/main/repositories/sql_repo.py) (SQL repositories), [`services/solver_service.py`](https://github.com/itaykapon1-lab/shiftapp-release/blob/main/services/solver_service.py) (Solver job orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Scheduling interface"]
  node_appui["Scheduling UI<br/>[App.jsx]"]
  node_hooks["UI lifecycle and CRUD"]
  node_scheduleview["Schedule and diagnostics views<br/>[ScheduleTab.jsx]"]
  node_tour["Interactive onboarding"]
end

subgraph group_api["API workflows"]
  node_routerhub["API router hub<br/>[routes.py]"]
  node_workerroutes["Worker CRUD<br/>[worker_routes.py]"]
  node_shiftroutes["Shift CRUD<br/>[shift_routes.py]"]
  node_constroutes["Constraint configuration"]
  node_solverroutes["Solver endpoints<br/>[solver_routes.py]"]
  node_sessionroutes["Session management<br/>[session_routes.py]"]
end

subgraph group_state["Domain and persistence"]
  node_models[("Relational and JSON records<br/>[models.py]")]
  node_repositories["SQL repositories<br/>[sql_repo.py]"]
  node_domain["Scheduling domain models"]
end

subgraph group_solve["Optimization engine"]
  node_solverservice["Solver job orchestration<br/>[solver_service.py]"]
  node_engine["MILP solver engine<br/>[solver_engine.py]"]
  node_constraints["Constraint registry and rules<br/>[definitions.py]"]
  node_diagnostics["Infeasibility diagnosis"]
end

subgraph group_integrations["Import and diagnosis"]
  node_excel["Excel import and export<br/>[excel_service.py]"]
  node_jobstore[("Solver job state")]
end

node_manager(("Schedule manager"))

node_manager -->|"enters schedule data"| node_appui
node_appui -->|"uses workflows"| node_hooks
node_appui -->|"renders results"| node_scheduleview
node_appui -->|"offers onboarding"| node_tour
node_appui -.->|"calls API"| node_routerhub
node_routerhub -->|"includes router"| node_workerroutes
node_routerhub -->|"includes router"| node_shiftroutes
node_routerhub -->|"includes router"| node_constroutes
node_routerhub -->|"includes router"| node_solverroutes
node_routerhub -->|"includes router"| node_sessionroutes
node_shiftroutes -->|"uses repository"| node_repositories
node_workerroutes -->|"uses repository"| node_repositories
node_repositories -->|"maps records"| node_models
node_repositories -->|"maps domain objects"| node_domain
node_solverroutes -->|"triggers jobs"| node_solverservice
node_solverservice -->|"loads schedule state"| node_repositories
node_solverservice -->|"runs solver"| node_engine
node_solverservice -->|"tracks jobs"| node_jobstore
node_engine -->|"applies rules"| node_constraints
node_engine -->|"delegates diagnosis"| node_diagnostics
node_constroutes -->|"reads configuration"| node_models
node_routerhub -->|"exposes Excel workflow"| node_excel
node_manager -->|"imports or exports workbook"| node_excel

click node_appui "https://github.com/itaykapon1-lab/shiftapp-release/blob/main/frontend/src/App.jsx"
click node_hooks "https://github.com/itaykapon1-lab/shiftapp-release/tree/main/frontend/src/hooks"
click node_scheduleview "https://github.com/itaykapon1-lab/shiftapp-release/blob/main/frontend/src/components/tabs/ScheduleTab.jsx"
click node_tour "https://github.com/itaykapon1-lab/shiftapp-release/tree/main/frontend/src/help"
click node_routerhub "https://github.com/itaykapon1-lab/shiftapp-release/blob/main/api/routes.py"
click node_workerroutes "https://github.com/itaykapon1-lab/shiftapp-release/blob/main/api/routers/worker_routes.py"
click node_shiftroutes "https://github.com/itaykapon1-lab/shiftapp-release/blob/main/api/routers/shift_routes.py"
click node_constroutes "https://github.com/itaykapon1-lab/shiftapp-release/blob/main/api/routers/constraint_routes.py"
click node_solverroutes "https://github.com/itaykapon1-lab/shiftapp-release/blob/main/api/routers/solver_routes.py"
click node_sessionroutes "https://github.com/itaykapon1-lab/shiftapp-release/blob/main/api/routers/session_routes.py"
click node_models "https://github.com/itaykapon1-lab/shiftapp-release/blob/main/data/models.py"
click node_repositories "https://github.com/itaykapon1-lab/shiftapp-release/blob/main/repositories/sql_repo.py"
click node_domain "https://github.com/itaykapon1-lab/shiftapp-release/tree/main/domain"
click node_solverservice "https://github.com/itaykapon1-lab/shiftapp-release/blob/main/services/solver_service.py"
click node_engine "https://github.com/itaykapon1-lab/shiftapp-release/blob/main/solver/solver_engine.py"
click node_constraints "https://github.com/itaykapon1-lab/shiftapp-release/blob/main/solver/constraints/definitions.py"
click node_diagnostics "https://github.com/itaykapon1-lab/shiftapp-release/blob/main/solver/diagnostics_engine.py"
click node_excel "https://github.com/itaykapon1-lab/shiftapp-release/blob/main/services/excel_service.py"
click node_jobstore "https://github.com/itaykapon1-lab/shiftapp-release/blob/main/services/solver_job_store.py"

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_appui,node_hooks,node_scheduleview,node_tour toneBlue
class node_routerhub,node_workerroutes,node_shiftroutes,node_constroutes,node_solverroutes,node_sessionroutes toneAmber
class node_models,node_repositories,node_domain toneMint
class node_solverservice,node_engine,node_constraints,node_diagnostics toneRose
class node_excel,node_jobstore,node_manager toneIndigo
```

## Components

### Scheduling interface

- [Scheduling UI](https://github.com/itaykapon1-lab/shiftapp-release/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [UI lifecycle and CRUD](https://github.com/itaykapon1-lab/shiftapp-release/tree/main/frontend/src/hooks): `frontend/src/hooks`
- [Schedule and diagnostics views](https://github.com/itaykapon1-lab/shiftapp-release/blob/main/frontend/src/components/tabs/ScheduleTab.jsx): `frontend/src/components/tabs/ScheduleTab.jsx`
- [Interactive onboarding](https://github.com/itaykapon1-lab/shiftapp-release/tree/main/frontend/src/help): `frontend/src/help`

### API workflows

- [API router hub](https://github.com/itaykapon1-lab/shiftapp-release/blob/main/api/routes.py): `api/routes.py`
- [Worker CRUD](https://github.com/itaykapon1-lab/shiftapp-release/blob/main/api/routers/worker_routes.py): `api/routers/worker_routes.py`
- [Shift CRUD](https://github.com/itaykapon1-lab/shiftapp-release/blob/main/api/routers/shift_routes.py): `api/routers/shift_routes.py`
- [Constraint configuration](https://github.com/itaykapon1-lab/shiftapp-release/blob/main/api/routers/constraint_routes.py): `api/routers/constraint_routes.py`
- [Solver endpoints](https://github.com/itaykapon1-lab/shiftapp-release/blob/main/api/routers/solver_routes.py): `api/routers/solver_routes.py`
- [Session management](https://github.com/itaykapon1-lab/shiftapp-release/blob/main/api/routers/session_routes.py): `api/routers/session_routes.py`

### Domain and persistence

- [Relational and JSON records](https://github.com/itaykapon1-lab/shiftapp-release/blob/main/data/models.py): `data/models.py`
- [SQL repositories](https://github.com/itaykapon1-lab/shiftapp-release/blob/main/repositories/sql_repo.py): `repositories/sql_repo.py`
- [Scheduling domain models](https://github.com/itaykapon1-lab/shiftapp-release/tree/main/domain): `domain`

### Optimization engine

- [Solver job orchestration](https://github.com/itaykapon1-lab/shiftapp-release/blob/main/services/solver_service.py): `services/solver_service.py`
- [MILP solver engine](https://github.com/itaykapon1-lab/shiftapp-release/blob/main/solver/solver_engine.py): `solver/solver_engine.py`
- [Constraint registry and rules](https://github.com/itaykapon1-lab/shiftapp-release/blob/main/solver/constraints/definitions.py): `solver/constraints/definitions.py`
- [Infeasibility diagnosis](https://github.com/itaykapon1-lab/shiftapp-release/blob/main/solver/diagnostics_engine.py): `solver/diagnostics_engine.py`

### Import and diagnosis

- [Excel import and export](https://github.com/itaykapon1-lab/shiftapp-release/blob/main/services/excel_service.py): `services/excel_service.py`
- [Solver job state](https://github.com/itaykapon1-lab/shiftapp-release/blob/main/services/solver_job_store.py): `services/solver_job_store.py`

### Other components

- **Schedule manager**

## Connections

- Schedule manager → Scheduling UI: enters schedule data (evidence: `README.md`)
- Scheduling UI → UI lifecycle and CRUD: uses workflows (evidence: `frontend/src/App.jsx`)
- Scheduling UI → Schedule and diagnostics views: renders results (evidence: `frontend/src/App.jsx`)
- Scheduling UI → Interactive onboarding: offers onboarding (evidence: `frontend/src/App.jsx`)
- Scheduling UI → API router hub: calls API
- API router hub → Worker CRUD: includes router (evidence: `api/routes.py`)
- API router hub → Shift CRUD: includes router (evidence: `api/routes.py`)
- API router hub → Constraint configuration: includes router (evidence: `api/routes.py`)
- API router hub → Solver endpoints: includes router (evidence: `api/routes.py`)
- API router hub → Session management: includes router (evidence: `api/routes.py`)
- Shift CRUD → SQL repositories: uses repository (evidence: `api/routers/shift_routes.py`)
- Worker CRUD → SQL repositories: uses repository (evidence: `api/routers/worker_routes.py`)
- SQL repositories → Relational and JSON records: maps records
- SQL repositories → Scheduling domain models: maps domain objects
- Solver endpoints → Solver job orchestration: triggers jobs (evidence: `api/routes.py`)
- Solver job orchestration → SQL repositories: loads schedule state (evidence: `services/solver_service.py`)
- Solver job orchestration → MILP solver engine: runs solver (evidence: `services/solver_service.py`)
- Solver job orchestration → Solver job state: tracks jobs (evidence: `services/solver_service.py`)
- MILP solver engine → Constraint registry and rules: applies rules (evidence: `solver/solver_engine.py`)
- MILP solver engine → Infeasibility diagnosis: delegates diagnosis (evidence: `solver/solver_engine.py`)
- Constraint configuration → Relational and JSON records: reads configuration (evidence: `api/routers/constraint_routes.py`)
- API router hub → Excel import and export: exposes Excel workflow (evidence: `api/routes.py`)
- Schedule manager → Excel import and export: imports or exports workbook (evidence: `README.md`)