# nader20-5/gillo-ai-services architecture

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

- Interactive diagram: https://gitdiagram.com/nader20-5/gillo-ai-services
- Repository: https://github.com/nader20-5/gillo-ai-services

## Overview

Taskove (Gillo) is a FastAPI AI service for an Agile platform. Its main workflow serves sprint analysis and task estimates through API routers, using task/sprint read models, feature engineering, and a versioned model registry with rule fallbacks; sprint analysis can also produce risk suggestions. Separate API branches support suggestion management, AI drafts, and chat. Background jobs repeat risk scans and maintain suggestion/profile state. The README also documents Model 1 estimation and Model 2 carry-over risk capabilities. Edges are limited to relationships visible in excerpts, the SOURCE INDEX, or the README; unsampled subsystems are represented without speculative wiring.

Main entry points: [`app/routers/sprints.py`](https://github.com/nader20-5/gillo-ai-services/blob/main/app/routers/sprints.py) (Sprint analysis), [`app/jobs/sprint_jobs.py`](https://github.com/nader20-5/gillo-ai-services/blob/main/app/jobs/sprint_jobs.py) (Sprint background jobs), [`app/main.py`](https://github.com/nader20-5/gillo-ai-services/blob/main/app/main.py) (FastAPI entrypoint), [`app/database.py`](https://github.com/nader20-5/gillo-ai-services/blob/main/app/database.py) (MongoDB access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_api["FastAPI entrypoint<br/>[main.py]"]
  node_auth["JWT access control<br/>[auth.py]"]
end

subgraph group_sprint["Sprint intelligence"]
  node_sprint_api["Sprint analysis<br/>[sprints.py]"]
  node_estimation["Estimation service"]
  node_features["Feature engineering<br/>[features.py]"]
  node_registry["Model registry<br/>[registry.py]"]
  node_snapshots["Agile read models<br/>[read_models.py]"]
  node_suggestion_api["Suggestion inbox<br/>[suggestions.py]"]
  node_benchmark_features["Offline features<br/>[features_v2.py]"]
  node_benchmark_replay["Benchmark replay<br/>[replay.py]"]
end

subgraph group_ai["AI interactions"]
  node_draft_api["Draft generation<br/>[drafts.py]"]
  node_chat_api["AI chat<br/>[chat.py]"]
  node_chat_tools["Chat tools<br/>[chat_tools.py]"]
  node_llm["LLM providers<br/>[llm_provider.py]"]
  node_llm_service["LLM service<br/>[llm.py]"]
  node_evaluation["Model 3 metrics<br/>[model3_metrics.py]"]
end

subgraph group_ops["State and operations"]
  node_database[("MongoDB access<br/>[database.py]")]
  node_jobs["Sprint background jobs<br/>[sprint_jobs.py]"]
  node_scheduler["Job scheduler<br/>[scheduler.py]"]
  node_events["Event consumer<br/>[consumer.py]"]
  node_privacy["Privacy controls<br/>[privacy.py]"]
end

node_user(("Agile user"))

node_user -->|"submits requests"| node_api
node_api -->|"routes requests"| node_sprint_api
node_api -->|"routes requests"| node_suggestion_api
node_api -->|"routes requests"| node_draft_api
node_api -->|"routes requests"| node_chat_api
node_api -->|"starts jobs"| node_scheduler
node_sprint_api -->|"reads and writes"| node_database
node_sprint_api -->|"computes estimates"| node_estimation
node_sprint_api -->|"builds features"| node_features
node_sprint_api -->|"scores tasks"| node_registry
node_sprint_api -->|"uses snapshots"| node_snapshots
node_sprint_api -.->|"creates warnings"| node_suggestion_api
node_suggestion_api -->|"reads and writes"| node_database
node_draft_api -->|"reads and writes"| node_database
node_draft_api -->|"requests generation"| node_llm_service
node_llm_service -->|"delegates generation"| node_llm
node_chat_api -->|"uses tools"| node_chat_tools
node_chat_api -->|"requests generation"| node_llm
node_chat_api -->|"reads and writes"| node_database
node_scheduler -->|"schedules jobs"| node_jobs
node_jobs -->|"reads and writes"| node_database
node_jobs -->|"builds snapshots"| node_snapshots
node_jobs -->|"scores sprints"| node_registry
node_jobs -->|"computes features"| node_features
node_jobs -->|"refreshes ratios"| node_estimation
node_events -->|"invokes job logic"| node_jobs
node_events -->|"uses controls"| node_privacy
node_registry -->|"validates contract"| node_features
node_registry -->|"uses feature definitions"| node_benchmark_features
node_benchmark_replay -->|"uses features"| node_benchmark_features

click node_api "https://github.com/nader20-5/gillo-ai-services/blob/main/app/main.py"
click node_auth "https://github.com/nader20-5/gillo-ai-services/blob/main/app/middleware/auth.py"
click node_sprint_api "https://github.com/nader20-5/gillo-ai-services/blob/main/app/routers/sprints.py"
click node_estimation "https://github.com/nader20-5/gillo-ai-services/blob/main/app/services/estimation_service.py"
click node_features "https://github.com/nader20-5/gillo-ai-services/blob/main/app/ml/features.py"
click node_registry "https://github.com/nader20-5/gillo-ai-services/blob/main/app/ml/registry.py"
click node_snapshots "https://github.com/nader20-5/gillo-ai-services/blob/main/app/models/read_models.py"
click node_suggestion_api "https://github.com/nader20-5/gillo-ai-services/blob/main/app/routers/suggestions.py"
click node_draft_api "https://github.com/nader20-5/gillo-ai-services/blob/main/app/routers/drafts.py"
click node_chat_api "https://github.com/nader20-5/gillo-ai-services/blob/main/app/routers/chat.py"
click node_chat_tools "https://github.com/nader20-5/gillo-ai-services/blob/main/app/services/chat_tools.py"
click node_llm "https://github.com/nader20-5/gillo-ai-services/blob/main/app/services/llm_provider.py"
click node_llm_service "https://github.com/nader20-5/gillo-ai-services/blob/main/app/services/llm.py"
click node_database "https://github.com/nader20-5/gillo-ai-services/blob/main/app/database.py"
click node_jobs "https://github.com/nader20-5/gillo-ai-services/blob/main/app/jobs/sprint_jobs.py"
click node_scheduler "https://github.com/nader20-5/gillo-ai-services/blob/main/app/jobs/scheduler.py"
click node_events "https://github.com/nader20-5/gillo-ai-services/blob/main/app/events/consumer.py"
click node_privacy "https://github.com/nader20-5/gillo-ai-services/blob/main/app/utils/privacy.py"
click node_benchmark_features "https://github.com/nader20-5/gillo-ai-services/blob/main/benchmark_v2/features_v2.py"
click node_benchmark_replay "https://github.com/nader20-5/gillo-ai-services/blob/main/benchmark_v2/replay.py"
click node_evaluation "https://github.com/nader20-5/gillo-ai-services/blob/main/app/evaluation/model3_metrics.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_api,node_auth,node_user toneBlue
class node_sprint_api,node_estimation,node_features,node_registry,node_snapshots,node_suggestion_api,node_benchmark_features,node_benchmark_replay toneAmber
class node_draft_api,node_chat_api,node_chat_tools,node_llm,node_llm_service,node_evaluation toneMint
class node_database,node_jobs,node_scheduler,node_events,node_privacy toneRose
```

## Components

### API and access

- [FastAPI entrypoint](https://github.com/nader20-5/gillo-ai-services/blob/main/app/main.py): `app/main.py`
- [JWT access control](https://github.com/nader20-5/gillo-ai-services/blob/main/app/middleware/auth.py): `app/middleware/auth.py`

### Sprint intelligence

- [Sprint analysis](https://github.com/nader20-5/gillo-ai-services/blob/main/app/routers/sprints.py): `app/routers/sprints.py`
- [Estimation service](https://github.com/nader20-5/gillo-ai-services/blob/main/app/services/estimation_service.py): `app/services/estimation_service.py`
- [Feature engineering](https://github.com/nader20-5/gillo-ai-services/blob/main/app/ml/features.py): `app/ml/features.py`
- [Model registry](https://github.com/nader20-5/gillo-ai-services/blob/main/app/ml/registry.py): `app/ml/registry.py`
- [Agile read models](https://github.com/nader20-5/gillo-ai-services/blob/main/app/models/read_models.py): `app/models/read_models.py`
- [Suggestion inbox](https://github.com/nader20-5/gillo-ai-services/blob/main/app/routers/suggestions.py): `app/routers/suggestions.py`
- [Offline features](https://github.com/nader20-5/gillo-ai-services/blob/main/benchmark_v2/features_v2.py): `benchmark_v2/features_v2.py`
- [Benchmark replay](https://github.com/nader20-5/gillo-ai-services/blob/main/benchmark_v2/replay.py): `benchmark_v2/replay.py`

### AI interactions

- [Draft generation](https://github.com/nader20-5/gillo-ai-services/blob/main/app/routers/drafts.py): `app/routers/drafts.py`
- [AI chat](https://github.com/nader20-5/gillo-ai-services/blob/main/app/routers/chat.py): `app/routers/chat.py`
- [Chat tools](https://github.com/nader20-5/gillo-ai-services/blob/main/app/services/chat_tools.py): `app/services/chat_tools.py`
- [LLM providers](https://github.com/nader20-5/gillo-ai-services/blob/main/app/services/llm_provider.py): `app/services/llm_provider.py`
- [LLM service](https://github.com/nader20-5/gillo-ai-services/blob/main/app/services/llm.py): `app/services/llm.py`
- [Model 3 metrics](https://github.com/nader20-5/gillo-ai-services/blob/main/app/evaluation/model3_metrics.py): `app/evaluation/model3_metrics.py`

### State and operations

- [MongoDB access](https://github.com/nader20-5/gillo-ai-services/blob/main/app/database.py): `app/database.py`
- [Sprint background jobs](https://github.com/nader20-5/gillo-ai-services/blob/main/app/jobs/sprint_jobs.py): `app/jobs/sprint_jobs.py`
- [Job scheduler](https://github.com/nader20-5/gillo-ai-services/blob/main/app/jobs/scheduler.py): `app/jobs/scheduler.py`
- [Event consumer](https://github.com/nader20-5/gillo-ai-services/blob/main/app/events/consumer.py): `app/events/consumer.py`
- [Privacy controls](https://github.com/nader20-5/gillo-ai-services/blob/main/app/utils/privacy.py): `app/utils/privacy.py`

### Other components

- **Agile user**

## Connections

- Agile user → FastAPI entrypoint: submits requests (evidence: `app/main.py`)
- FastAPI entrypoint → Sprint analysis: routes requests (evidence: `app/main.py`)
- FastAPI entrypoint → Suggestion inbox: routes requests (evidence: `app/main.py`)
- FastAPI entrypoint → Draft generation: routes requests (evidence: `app/main.py`)
- FastAPI entrypoint → AI chat: routes requests (evidence: `app/main.py`)
- FastAPI entrypoint → Job scheduler: starts jobs (evidence: `app/main.py`)
- Sprint analysis → MongoDB access: reads and writes (evidence: `app/routers/sprints.py`)
- Sprint analysis → Estimation service: computes estimates (evidence: `app/routers/sprints.py`)
- Sprint analysis → Feature engineering: builds features (evidence: `app/routers/sprints.py`)
- Sprint analysis → Model registry: scores tasks (evidence: `app/routers/sprints.py`)
- Sprint analysis → Agile read models: uses snapshots (evidence: `app/routers/sprints.py`)
- Sprint analysis → Suggestion inbox: creates warnings
- Suggestion inbox → MongoDB access: reads and writes (evidence: `app/routers/suggestions.py`)
- Draft generation → MongoDB access: reads and writes (evidence: `app/routers/drafts.py`)
- Draft generation → LLM service: requests generation (evidence: `app/routers/drafts.py`)
- LLM service → LLM providers: delegates generation (evidence: `app/services/llm.py`)
- AI chat → Chat tools: uses tools (evidence: `app/routers/chat.py`)
- AI chat → LLM providers: requests generation (evidence: `app/routers/chat.py`)
- AI chat → MongoDB access: reads and writes (evidence: `app/routers/chat.py`)
- Job scheduler → Sprint background jobs: schedules jobs (evidence: `app/jobs/scheduler.py`)
- Sprint background jobs → MongoDB access: reads and writes (evidence: `app/jobs/sprint_jobs.py`)
- Sprint background jobs → Agile read models: builds snapshots (evidence: `app/jobs/sprint_jobs.py`)
- Sprint background jobs → Model registry: scores sprints (evidence: `app/jobs/sprint_jobs.py`)
- Sprint background jobs → Feature engineering: computes features (evidence: `app/jobs/sprint_jobs.py`)
- Sprint background jobs → Estimation service: refreshes ratios (evidence: `app/jobs/sprint_jobs.py`)
- Event consumer → Sprint background jobs: invokes job logic (evidence: `app/events/consumer.py`)
- Event consumer → Privacy controls: uses controls (evidence: `app/events/consumer.py`)
- Model registry → Feature engineering: validates contract (evidence: `app/ml/registry.py`)
- Model registry → Offline features: uses feature definitions (evidence: `app/ml/registry.py`)
- Benchmark replay → Offline features: uses features (evidence: `benchmark_v2/scripts/run_model2_final_benchmarks.py`)
