# bishoy-mokhless/agentic-engineering-assessment architecture

> Architecture diagram of the GitHub repository bishoy-mokhless/agentic-engineering-assessment, 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/bishoy-mokhless/agentic-engineering-assessment
- Repository: https://github.com/bishoy-mokhless/agentic-engineering-assessment

## Overview

Retention combines workforce records with external labour-market indicators, builds curated analytical data, and serves retention measures and signal comparisons through an API and interactive dashboard. The documented user path is dashboard filters and tabs → API routes → dashboard queries → curated data → cohort, turnover, association, and trust results. The CLI also runs an offline or refresh pipeline. Sampled source confirms ingestion fallback and snapshot storage, API wiring, and query ownership; some pipeline internals and other documented-but-unsampled wiring are represented only at the subsystem level.

Main entry points: [`src/retention/pipeline/ingest.py`](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/pipeline/ingest.py) (Ingestion), [`src/retention/pipeline/job.py`](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/pipeline/job.py) (Pipeline job), [`src/retention/pipeline/curate.py`](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/pipeline/curate.py) (Curation), [`src/retention/api/app.py`](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/api/app.py) (API application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Data pipeline"]
  node_cli["CLI<br/>[cli.py]"]
  node_job["Pipeline job<br/>[job.py]"]
  node_ingest["Ingestion<br/>[ingest.py]"]
  node_eurostat["Eurostat client<br/>[eurostat.py]"]
  node_worldbank["World Bank client<br/>[worldbank.py]"]
  node_hrclient["HR file client<br/>[hr_files.py]"]
end

subgraph group_analysis["Curation and analysis"]
  node_curate["Curation<br/>[curate.py]"]
  node_hrcuration["HR curation<br/>[hr_curation.py]"]
  node_indicatorcuration["Indicator curation"]
  node_metrics["Metrics<br/>[metrics.py]"]
  node_analyse["Analysis<br/>[analyse.py]"]
  node_association["Signal association<br/>[association.py]"]
end

subgraph group_serving["API and dashboard"]
  node_app["API application<br/>[app.py]"]
  node_objectives["Retention routes<br/>[objectives.py]"]
  node_signals["Signal routes<br/>[signals.py]"]
  node_trust["Trust routes<br/>[trust.py]"]
  node_queries["Dashboard queries"]
  node_dashboard["Interactive dashboard<br/>[app.js]"]
end

subgraph group_storage["Data storage"]
  node_raw[("Raw snapshots<br/>[raw_repository.py]")]
  node_curatedrepo[("Curated repository")]
  node_curatedstore[("Curated data store<br/>[curated_store.py]")]
end

node_operator(("Operator"))
node_analyst(("Dashboard user"))
node_providers{{"External data providers"}}
node_hrpack["Delivered HR pack"]

node_operator -->|"runs commands"| node_cli
node_cli -->|"starts pipeline"| node_job
node_job -->|"runs ingest"| node_ingest
node_job -->|"runs curation"| node_curate
node_job -->|"runs metrics"| node_metrics
node_job -->|"runs analysis"| node_analyse
node_ingest -.->|"fetches indicators"| node_eurostat
node_ingest -.->|"fetches indicators"| node_worldbank
node_ingest -->|"checks HR pack"| node_hrclient
node_eurostat -->|"requests data"| node_providers
node_worldbank -->|"requests data"| node_providers
node_hrclient -->|"reads files"| node_hrpack
node_ingest -->|"saves snapshots"| node_raw
node_ingest -->|"reads latest"| node_raw
node_curate -->|"reads snapshots"| node_raw
node_curate -->|"curates workforce"| node_hrcuration
node_curate -->|"curates indicators"| node_indicatorcuration
node_curate -->|"writes layers"| node_curatedrepo
node_metrics -->|"writes metrics"| node_curatedrepo
node_analyse -->|"writes analysis"| node_curatedrepo
node_analyse -->|"computes association"| node_association
node_operator -->|"serves application"| node_cli
node_cli -->|"starts server"| node_app
node_app -->|"creates store"| node_curatedstore
node_app -->|"registers routes"| node_objectives
node_app -->|"registers routes"| node_signals
node_app -->|"registers routes"| node_trust
node_analyst -->|"selects filters"| node_dashboard
node_dashboard -->|"requests retention"| node_objectives
node_dashboard -->|"requests signals"| node_signals
node_dashboard -->|"requests trust"| node_trust
node_objectives -->|"calls queries"| node_queries
node_signals -->|"calls queries"| node_queries
node_trust -->|"calls queries"| node_queries
node_queries -->|"reads curated data"| node_curatedstore

click node_cli "https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/cli.py"
click node_job "https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/pipeline/job.py"
click node_ingest "https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/pipeline/ingest.py"
click node_eurostat "https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/client/eurostat.py"
click node_worldbank "https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/client/worldbank.py"
click node_hrclient "https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/client/hr_files.py"
click node_curate "https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/pipeline/curate.py"
click node_hrcuration "https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/service/hr_curation.py"
click node_indicatorcuration "https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/service/indicator_curation.py"
click node_metrics "https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/pipeline/metrics.py"
click node_analyse "https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/pipeline/analyse.py"
click node_association "https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/service/association.py"
click node_raw "https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/repository/raw_repository.py"
click node_curatedrepo "https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/repository/curated_repository.py"
click node_curatedstore "https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/repository/curated_store.py"
click node_app "https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/api/app.py"
click node_objectives "https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/api/routers/objectives.py"
click node_signals "https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/api/routers/signals.py"
click node_trust "https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/api/routers/trust.py"
click node_queries "https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/service/dashboard_queries.py"
click node_dashboard "https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/dashboard/app.js"

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_job,node_ingest,node_eurostat,node_worldbank,node_hrclient,node_analyst toneBlue
class node_curate,node_hrcuration,node_indicatorcuration,node_metrics,node_analyse,node_association toneAmber
class node_app,node_objectives,node_signals,node_trust,node_queries,node_dashboard toneMint
class node_raw,node_curatedrepo,node_curatedstore toneRose
class node_operator,node_providers,node_hrpack toneIndigo
```

## Components

### Data pipeline

- [CLI](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/cli.py): `src/retention/cli.py`
- [Pipeline job](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/pipeline/job.py): `src/retention/pipeline/job.py`
- [Ingestion](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/pipeline/ingest.py): `src/retention/pipeline/ingest.py`
- [Eurostat client](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/client/eurostat.py): `src/retention/client/eurostat.py`
- [World Bank client](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/client/worldbank.py): `src/retention/client/worldbank.py`
- [HR file client](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/client/hr_files.py): `src/retention/client/hr_files.py`

### Curation and analysis

- [Curation](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/pipeline/curate.py): `src/retention/pipeline/curate.py`
- [HR curation](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/service/hr_curation.py): `src/retention/service/hr_curation.py`
- [Indicator curation](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/service/indicator_curation.py): `src/retention/service/indicator_curation.py`
- [Metrics](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/pipeline/metrics.py): `src/retention/pipeline/metrics.py`
- [Analysis](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/pipeline/analyse.py): `src/retention/pipeline/analyse.py`
- [Signal association](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/service/association.py): `src/retention/service/association.py`

### API and dashboard

- [API application](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/api/app.py): `src/retention/api/app.py`
- [Retention routes](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/api/routers/objectives.py): `src/retention/api/routers/objectives.py`
- [Signal routes](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/api/routers/signals.py): `src/retention/api/routers/signals.py`
- [Trust routes](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/api/routers/trust.py): `src/retention/api/routers/trust.py`
- [Dashboard queries](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/service/dashboard_queries.py): `src/retention/service/dashboard_queries.py`
- [Interactive dashboard](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/dashboard/app.js): `dashboard/app.js`

### Data storage

- [Raw snapshots](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/repository/raw_repository.py): `src/retention/repository/raw_repository.py`
- [Curated repository](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/repository/curated_repository.py): `src/retention/repository/curated_repository.py`
- [Curated data store](https://github.com/bishoy-mokhless/agentic-engineering-assessment/blob/main/src/retention/repository/curated_store.py): `src/retention/repository/curated_store.py`

### Other components

- **Operator**
- **Dashboard user**
- **External data providers**
- **Delivered HR pack**

## Connections

- Operator → CLI: runs commands
- CLI → Pipeline job: starts pipeline
- Pipeline job → Ingestion: runs ingest
- Pipeline job → Curation: runs curation
- Pipeline job → Metrics: runs metrics
- Pipeline job → Analysis: runs analysis
- Ingestion → Eurostat client: fetches indicators
- Ingestion → World Bank client: fetches indicators
- Ingestion → HR file client: checks HR pack
- Eurostat client → External data providers: requests data
- World Bank client → External data providers: requests data
- HR file client → Delivered HR pack: reads files
- Ingestion → Raw snapshots: saves snapshots
- Ingestion → Raw snapshots: reads latest
- Curation → Raw snapshots: reads snapshots
- Curation → HR curation: curates workforce
- Curation → Indicator curation: curates indicators
- Curation → Curated repository: writes layers
- Metrics → Curated repository: writes metrics
- Analysis → Curated repository: writes analysis
- Analysis → Signal association: computes association
- Operator → CLI: serves application
- CLI → API application: starts server
- API application → Curated data store: creates store
- API application → Retention routes: registers routes
- API application → Signal routes: registers routes
- API application → Trust routes: registers routes
- Dashboard user → Interactive dashboard: selects filters
- Interactive dashboard → Retention routes: requests retention
- Interactive dashboard → Signal routes: requests signals
- Interactive dashboard → Trust routes: requests trust
- Retention routes → Dashboard queries: calls queries
- Signal routes → Dashboard queries: calls queries
- Trust routes → Dashboard queries: calls queries
- Dashboard queries → Curated data store: reads curated data