# long-alex/cc-wfm architecture

> Architecture diagram of the GitHub repository long-alex/cc-wfm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/long-alex/cc-wfm
- Repository: https://github.com/long-alex/cc-wfm

## Overview

CC-WFM is a call-center workforce-management system with a two-stage forecasting and scheduling workflow, exposed through CLI and REST adapters. Inputs are converted and validated, then shared application services orchestrate forecasting or schedule optimization; results are persisted and rendered as reports or staffing-plan workbooks. The README documents Excel/JSON conversion, evaluation and tuning, templates, run-status/artifact APIs, HTML reports, and staffing-plan generation. Sampled source confirms key API and orchestration links; unsampled runtime links are included only where README capability descriptions support them.

Main entry points: [`adapters/api/v1/common/run_controller.py`](https://github.com/long-alex/cc-wfm/blob/main/adapters/api/v1/common/run_controller.py) (Run controllers), [`application/services.py`](https://github.com/long-alex/cc-wfm/blob/main/application/services.py) (Run orchestration), [`core/forecasting/pipeline.py`](https://github.com/long-alex/cc-wfm/blob/main/core/forecasting/pipeline.py) (Forecast pipeline), [`adapters/cli`](https://github.com/long-alex/cc-wfm/tree/main/adapters/cli) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI commands"]
  node_rest["REST API<br/>[main.py]"]
  node_web["Web console<br/>[controller.py]"]
  node_run_controller["Run controllers<br/>[run_controller.py]"]
  node_run_state[("Run state and artifacts<br/>[run_log.py]")]
  node_templates["Excel templates<br/>[controller.py]"]
end

subgraph group_application["Application workflow"]
  node_converters["Excel converters"]
  node_validation["Input validation<br/>[validators.py]"]
  node_services["Run orchestration<br/>[services.py]"]
end

subgraph group_forecast["Forecasting"]
  node_forecast_pipeline["Forecast pipeline<br/>[pipeline.py]"]
  node_selection["Model selection<br/>[select.py]"]
  node_modeling["Forecast models<br/>[models.py]"]
  node_staffing["Erlang C staffing<br/>[calculator.py]"]
end

subgraph group_schedule["Scheduling"]
  node_schedule_solver["Schedule solver<br/>[solve.py]"]
  node_constraints["Schedule constraints<br/>[coverage.py]"]
  node_solution["Schedule solution<br/>[solution.py]"]
end

subgraph group_outputs["Results and reporting"]
  node_outputs["Output writers"]
  node_reports["HTML reports"]
  node_plan["Staffing workbook"]
end

node_operator(("Operator"))

node_operator -->|"runs commands"| node_cli
node_operator -->|"uses console"| node_web
node_operator -->|"calls API"| node_rest
node_web -->|"uses same-origin API"| node_rest
node_rest -->|"dispatches routes"| node_run_controller
node_run_controller -->|"converts upload"| node_converters
node_run_controller -->|"validates input"| node_validation
node_run_controller -->|"records run status"| node_run_state
node_cli -->|"converts Excel"| node_converters
node_cli -->|"starts run"| node_services
node_run_controller -->|"queues task"| node_services
node_services -->|"runs forecasting"| node_forecast_pipeline
node_forecast_pipeline -->|"selects models"| node_selection
node_forecast_pipeline -->|"trains and predicts"| node_modeling
node_forecast_pipeline -->|"calculates staffing"| node_staffing
node_services -->|"solves schedule"| node_schedule_solver
node_schedule_solver -->|"builds coverage rules"| node_constraints
node_schedule_solver -->|"produces solution"| node_solution
node_services -->|"writes results"| node_outputs
node_outputs -->|"renders reports"| node_reports
node_outputs -->|"generates workbook"| node_plan
node_operator -->|"downloads template"| node_templates
node_run_controller -->|"reads run status"| node_run_state

click node_cli "https://github.com/long-alex/cc-wfm/tree/main/adapters/cli"
click node_rest "https://github.com/long-alex/cc-wfm/blob/main/adapters/api/main.py"
click node_web "https://github.com/long-alex/cc-wfm/blob/main/adapters/api/web/controller.py"
click node_run_controller "https://github.com/long-alex/cc-wfm/blob/main/adapters/api/v1/common/run_controller.py"
click node_converters "https://github.com/long-alex/cc-wfm/tree/main/application/converters"
click node_validation "https://github.com/long-alex/cc-wfm/blob/main/validation/validators.py"
click node_services "https://github.com/long-alex/cc-wfm/blob/main/application/services.py"
click node_forecast_pipeline "https://github.com/long-alex/cc-wfm/blob/main/core/forecasting/pipeline.py"
click node_selection "https://github.com/long-alex/cc-wfm/blob/main/core/forecasting/selection/select.py"
click node_modeling "https://github.com/long-alex/cc-wfm/blob/main/core/forecasting/modeling/models.py"
click node_staffing "https://github.com/long-alex/cc-wfm/blob/main/core/staffing/calculator.py"
click node_schedule_solver "https://github.com/long-alex/cc-wfm/blob/main/core/scheduling/model/solve.py"
click node_constraints "https://github.com/long-alex/cc-wfm/blob/main/core/scheduling/constraints/coverage.py"
click node_solution "https://github.com/long-alex/cc-wfm/blob/main/core/scheduling/solution.py"
click node_outputs "https://github.com/long-alex/cc-wfm/tree/main/application/outputs"
click node_reports "https://github.com/long-alex/cc-wfm/tree/main/adapters/reporting"
click node_plan "https://github.com/long-alex/cc-wfm/tree/main/adapters/staffing_plan"
click node_run_state "https://github.com/long-alex/cc-wfm/blob/main/adapters/api/runtime/run_log.py"
click node_templates "https://github.com/long-alex/cc-wfm/blob/main/adapters/api/v1/common/templates/controller.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_cli,node_rest,node_web,node_run_controller,node_run_state,node_templates toneBlue
class node_converters,node_validation,node_services toneAmber
class node_forecast_pipeline,node_selection,node_modeling,node_staffing toneMint
class node_schedule_solver,node_constraints,node_solution toneRose
class node_outputs,node_reports,node_plan,node_operator toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/long-alex/cc-wfm/tree/main/adapters/cli): `adapters/cli`
- [REST API](https://github.com/long-alex/cc-wfm/blob/main/adapters/api/main.py): `adapters/api/main.py`
- [Web console](https://github.com/long-alex/cc-wfm/blob/main/adapters/api/web/controller.py): `adapters/api/web/controller.py`
- [Run controllers](https://github.com/long-alex/cc-wfm/blob/main/adapters/api/v1/common/run_controller.py): `adapters/api/v1/common/run_controller.py`
- [Run state and artifacts](https://github.com/long-alex/cc-wfm/blob/main/adapters/api/runtime/run_log.py): `adapters/api/runtime/run_log.py`
- [Excel templates](https://github.com/long-alex/cc-wfm/blob/main/adapters/api/v1/common/templates/controller.py): `adapters/api/v1/common/templates/controller.py`

### Application workflow

- [Excel converters](https://github.com/long-alex/cc-wfm/tree/main/application/converters): `application/converters`
- [Input validation](https://github.com/long-alex/cc-wfm/blob/main/validation/validators.py): `validation/validators.py`
- [Run orchestration](https://github.com/long-alex/cc-wfm/blob/main/application/services.py): `application/services.py`

### Forecasting

- [Forecast pipeline](https://github.com/long-alex/cc-wfm/blob/main/core/forecasting/pipeline.py): `core/forecasting/pipeline.py`
- [Model selection](https://github.com/long-alex/cc-wfm/blob/main/core/forecasting/selection/select.py): `core/forecasting/selection/select.py`
- [Forecast models](https://github.com/long-alex/cc-wfm/blob/main/core/forecasting/modeling/models.py): `core/forecasting/modeling/models.py`
- [Erlang C staffing](https://github.com/long-alex/cc-wfm/blob/main/core/staffing/calculator.py): `core/staffing/calculator.py`

### Scheduling

- [Schedule solver](https://github.com/long-alex/cc-wfm/blob/main/core/scheduling/model/solve.py): `core/scheduling/model/solve.py`
- [Schedule constraints](https://github.com/long-alex/cc-wfm/blob/main/core/scheduling/constraints/coverage.py): `core/scheduling/constraints/coverage.py`
- [Schedule solution](https://github.com/long-alex/cc-wfm/blob/main/core/scheduling/solution.py): `core/scheduling/solution.py`

### Results and reporting

- [Output writers](https://github.com/long-alex/cc-wfm/tree/main/application/outputs): `application/outputs`
- [HTML reports](https://github.com/long-alex/cc-wfm/tree/main/adapters/reporting): `adapters/reporting`
- [Staffing workbook](https://github.com/long-alex/cc-wfm/tree/main/adapters/staffing_plan): `adapters/staffing_plan`

### Other components

- **Operator**

## Connections

- Operator → CLI commands: runs commands
- Operator → Web console: uses console
- Operator → REST API: calls API
- Web console → REST API: uses same-origin API
- REST API → Run controllers: dispatches routes
- Run controllers → Excel converters: converts upload
- Run controllers → Input validation: validates input
- Run controllers → Run state and artifacts: records run status
- CLI commands → Excel converters: converts Excel
- CLI commands → Run orchestration: starts run
- Run controllers → Run orchestration: queues task
- Run orchestration → Forecast pipeline: runs forecasting
- Forecast pipeline → Model selection: selects models
- Forecast pipeline → Forecast models: trains and predicts
- Forecast pipeline → Erlang C staffing: calculates staffing
- Run orchestration → Schedule solver: solves schedule
- Schedule solver → Schedule constraints: builds coverage rules
- Schedule solver → Schedule solution: produces solution
- Run orchestration → Output writers: writes results
- Output writers → HTML reports: renders reports
- Output writers → Staffing workbook: generates workbook
- Operator → Excel templates: downloads template
- Run controllers → Run state and artifacts: reads run status