# dharmateja03/harmony-ai architecture

> Architecture diagram of the GitHub repository dharmateja03/harmony-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dharmateja03/harmony-ai
- Repository: https://github.com/dharmateja03/harmony-ai

## Overview

1. **What this repo is**
   - A stateless production scheduling service that accepts one scheduling request, solves it once, and returns a feasible schedule optimized for minimum tardiness.
   - The core architecture is a thin API wrapper around a constraint-programming solver.

2. **Primary request flow**
   - The main path is: `POST /schedule` → request validation → client-specific parsing → canonical scheduling problem → CP-SAT solve → KPI calculation → JSON response.
   - This flow is centered in `app/main.py`, `app/adapters/client_a.py`, `app/scheduler/solver.py`, and `app/kpis/calculator.py`.

3. **API boundary**
   - `app/models/api.py` defines the external request/response schema used by the HTTP layer.
   - `app/main.py` exposes the FastAPI app and is the integration point between HTTP and the scheduler pipeline.

4. **Client adapter boundary**
   - `app/adapters/client_a.py` translates the incoming client JSON format into the internal scheduling model.
   - This is the place where client-specific field names, validation assumptions, and support for objective modes are handled.
   - The design intentionally isolates input formats so a second client can be added without changing the solver.

5. **Canonical internal domain model**
   - `app/models/internal.py` holds the solver-facing dataclasses such as resources, products, route steps, time windows, changeover matrices, and objective config.
   - The solver operates only on these typed internal objects, not on raw JSON or client-specific shapes.
   - This boundary is the repository’s main “model translation” seam.

6. **Constraint-solving core**
   - `app/scheduler/solver.py` builds the OR-Tools CP-SAT model.
   - The model includes operation start variables, resource assignment booleans, window-fit logic, no-overlap constraints, changeover gaps, and precedence links between steps in a product route.
   - The solver is the only place where scheduling feasibility is enforced.

7. **Objective handling**
   - `app/scheduler/objectives.py` defines objective-building logic, with the active objective selected through a registry-style pattern.
   - The README indicates the current optimization target is total tardiness, but the structure allows adding other objective modes without changing the solver’s overall flow.

8. **Output and KPIs**
   - After solving, `app/kpis/calculator.py` derives operational KPIs from the chosen assignment list.
   - This means the solver returns a schedule, and the KPI layer enriches it for the API response rather than influencing the feasibility model.

9. **Auxiliary presentation tools**
   - `app/ui.py` and `app/viz.py` appear to support local viewing or visualization of schedules rather than the service’s main request path.
   - They are adjacent utilities, not core scheduling dependencies.

10. **Operational characteristics**
   - The service runs either in Docker or directly under Uvicorn with Python 3.12+.
   - It is deterministic by design: single worker plus fixed seed, so the same input should produce the same schedule.
   - There is no persistence, authentication, or external service dependency; each scheduling request is independent.

11. **Feasibility and failure handling**
   - The adapter/solver path includes basic infeasibility checks, such as missing capability or operations that cannot fit in any working window.
   - If the solver still proves infeasibility, the response is a generic infeasible result rather than detailed conflict analysis.

12. **Testing surface**
   - The tests cover infeasible cases, invariants, and KPI correctness, which maps directly to the main architectural risks: feasibility, constraint correctness, and output interpretation.
   - This supports the repo’s central contract: valid inputs should either yield a consistent feasible schedule or a clear infeasible outcome.

Main entry points: [`app/main.py`](https://github.com/dharmateja03/harmony-ai/blob/main/app/main.py) (Main API), [`app/scheduler/solver.py`](https://github.com/dharmateja03/harmony-ai/blob/main/app/scheduler/solver.py) (CP-SAT solver), [`tests/conftest.py`](https://github.com/dharmateja03/harmony-ai/blob/main/tests/conftest.py) (Test setup), [`app/adapters/client_a.py`](https://github.com/dharmateja03/harmony-ai/blob/main/app/adapters/client_a.py) (Client adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API layer"]
  node_app_main["Main API<br/>fastapi entrypoint<br/>[main.py]"]
  node_app_api_models["API models<br/>request/response schema<br/>[api.py]"]
end

subgraph group_domain["Domain model"]
  node_client_a["Client adapter<br/>input translator<br/>[client_a.py]"]
  node_internal_model["Internal model<br/>solver dataclasses<br/>[internal.py]"]
end

subgraph group_opt["Optimization core"]
  node_objectives{{"Objectives<br/>objective registry<br/>[objectives.py]"}}
  node_solver["CP-SAT solver<br/>constraint model<br/>[solver.py]"]
end

subgraph group_output["Output layer"]
  node_kpi_calc["KPI calc<br/>metrics derivation<br/>[calculator.py]"]
  node_ui(("UI helper<br/>local viewer<br/>[ui.py]"))
  node_viz(("Viz helper<br/>visualization<br/>[viz.py]"))
end

subgraph group_quality["Quality checks"]
  node_tests_infeasible["Infeasible tests<br/>test suite<br/>[test_infeasible.py]"]
  node_tests_invariants["Invariant tests<br/>test suite<br/>[test_invariants.py]"]
  node_tests_kpis["KPI tests<br/>test suite<br/>[test_kpis.py]"]
  node_conftest["Test setup<br/>fixtures<br/>[conftest.py]"]
end

node_app_main -->|"validates/serializes"| node_app_api_models
node_app_main -->|"dispatches"| node_client_a
node_client_a -->|"builds"| node_internal_model
node_internal_model -->|"feeds"| node_solver
node_solver -->|"selects objective"| node_objectives
node_solver -->|"returns solution"| node_kpi_calc
node_kpi_calc -->|"enriches response"| node_app_main
node_app_main -.->|"optional view"| node_ui
node_app_main -.->|"optional render"| node_viz
node_tests_infeasible -.->|"covers"| node_client_a
node_tests_invariants -.->|"covers"| node_solver
node_tests_kpis -.->|"covers"| node_kpi_calc
node_conftest -.->|"supports"| node_tests_infeasible
node_conftest -.->|"supports"| node_tests_invariants
node_conftest -.->|"supports"| node_tests_kpis

click node_app_main "https://github.com/dharmateja03/harmony-ai/blob/main/app/main.py"
click node_app_api_models "https://github.com/dharmateja03/harmony-ai/blob/main/app/models/api.py"
click node_client_a "https://github.com/dharmateja03/harmony-ai/blob/main/app/adapters/client_a.py"
click node_internal_model "https://github.com/dharmateja03/harmony-ai/blob/main/app/models/internal.py"
click node_objectives "https://github.com/dharmateja03/harmony-ai/blob/main/app/scheduler/objectives.py"
click node_solver "https://github.com/dharmateja03/harmony-ai/blob/main/app/scheduler/solver.py"
click node_kpi_calc "https://github.com/dharmateja03/harmony-ai/blob/main/app/kpis/calculator.py"
click node_ui "https://github.com/dharmateja03/harmony-ai/blob/main/app/ui.py"
click node_viz "https://github.com/dharmateja03/harmony-ai/blob/main/app/viz.py"
click node_tests_infeasible "https://github.com/dharmateja03/harmony-ai/blob/main/tests/test_infeasible.py"
click node_tests_invariants "https://github.com/dharmateja03/harmony-ai/blob/main/tests/test_invariants.py"
click node_tests_kpis "https://github.com/dharmateja03/harmony-ai/blob/main/tests/test_kpis.py"
click node_conftest "https://github.com/dharmateja03/harmony-ai/blob/main/tests/conftest.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_app_main,node_app_api_models toneBlue
class node_client_a,node_internal_model toneAmber
class node_objectives,node_solver toneMint
class node_kpi_calc,node_ui,node_viz toneRose
class node_tests_infeasible,node_tests_invariants,node_tests_kpis,node_conftest toneIndigo
```

## Components

### API layer

HTTP entrypoint and external contract

- [Main API](https://github.com/dharmateja03/harmony-ai/blob/main/app/main.py): fastapi entrypoint · Exposes POST /schedule and orchestrates the request pipeline · `app/main.py`
- [API models](https://github.com/dharmateja03/harmony-ai/blob/main/app/models/api.py): request/response schema · External HTTP payload definitions · `app/models/api.py`

### Domain model

Client translation and solver-facing types

- [Client adapter](https://github.com/dharmateja03/harmony-ai/blob/main/app/adapters/client_a.py): input translator · Maps client JSON into canonical scheduling input · `app/adapters/client_a.py`
- [Internal model](https://github.com/dharmateja03/harmony-ai/blob/main/app/models/internal.py): solver dataclasses · Canonical resources, routes, windows, changeovers, and objective config · `app/models/internal.py`

### Optimization core

Constraint solving and objective selection

- [Objectives](https://github.com/dharmateja03/harmony-ai/blob/main/app/scheduler/objectives.py): objective registry · Builds objective terms such as total tardiness · `app/scheduler/objectives.py`
- [CP-SAT solver](https://github.com/dharmateja03/harmony-ai/blob/main/app/scheduler/solver.py): constraint model · Builds feasibility model and searches for a schedule · `app/scheduler/solver.py`

### Output layer

KPI enrichment and local viewing utilities

- [KPI calc](https://github.com/dharmateja03/harmony-ai/blob/main/app/kpis/calculator.py): metrics derivation · Computes operational KPIs from the solved assignment · `app/kpis/calculator.py`
- [UI helper](https://github.com/dharmateja03/harmony-ai/blob/main/app/ui.py): local viewer · Ad hoc schedule presentation utility · `app/ui.py`
- [Viz helper](https://github.com/dharmateja03/harmony-ai/blob/main/app/viz.py): visualization · Schedule visualization utility · `app/viz.py`

### Quality checks

Tests covering feasibility and output correctness

- [Infeasible tests](https://github.com/dharmateja03/harmony-ai/blob/main/tests/test_infeasible.py): test suite · Covers impossible schedules and failure handling · `tests/test_infeasible.py`
- [Invariant tests](https://github.com/dharmateja03/harmony-ai/blob/main/tests/test_invariants.py): test suite · Checks schedule consistency and constraint invariants · `tests/test_invariants.py`
- [KPI tests](https://github.com/dharmateja03/harmony-ai/blob/main/tests/test_kpis.py): test suite · Validates KPI calculations on solved schedules · `tests/test_kpis.py`
- [Test setup](https://github.com/dharmateja03/harmony-ai/blob/main/tests/conftest.py): fixtures · Shared pytest fixtures and test wiring · `tests/conftest.py`

## Connections

- Main API → API models: validates/serializes · HTTP layer uses the external request and response schema
- Main API → Client adapter: dispatches · Main endpoint hands request payload to the client adapter
- Client adapter → Internal model: builds · Adapter converts client JSON into canonical solver input
- Internal model → CP-SAT solver: feeds · Solver consumes typed internal scheduling objects
- CP-SAT solver → Objectives: selects objective · Solver asks the objective registry for the active optimization mode
- CP-SAT solver → KPI calc: returns solution · Solved assignment is passed to KPI computation
- KPI calc → Main API: enriches response · KPIs are added before the API response is returned
- Main API → UI helper: optional view · Local utility path for viewing schedules
- Main API → Viz helper: optional render · Local visualization support adjacent to the main service
- Infeasible tests → Client adapter: covers · Tests exercise parsing and infeasibility paths
- Invariant tests → CP-SAT solver: covers · Tests verify feasibility and scheduling invariants
- KPI tests → KPI calc: covers · Tests verify KPI derivation from solved schedules
- Test setup → Infeasible tests: supports · Shared fixtures support infeasibility scenarios
- Test setup → Invariant tests: supports · Shared fixtures support invariant checks
- Test setup → KPI tests: supports · Shared fixtures support KPI checks
