# ife-banks/tender-intelligence architecture

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

- Interactive diagram: https://gitdiagram.com/ife-banks/tender-intelligence
- Repository: https://github.com/ife-banks/tender-intelligence

## Overview

Tender Intelligence monitors configured tender sources and notifies people with an evidence-grounded apply/no-apply verdict; it does not submit applications. The principal workflow is scheduled discovery, deduplication, document acquisition and processing, triage, deadline extraction, verdict generation, then notification with attachments or links. The admin app provides configuration and operational visibility, while audit and alerting track failures and recovery. The graph combines sampled implementation with workflow capabilities documented in the README; detailed coordinator wiring was not sampled, so only documented stage relationships are shown.

Main entry points: [`src/tender_intelligence/orchestrator/coordinator.py`](https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/orchestrator/coordinator.py) (Run coordinator), [`src/tender_intelligence/db/engine.py`](https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/db/engine.py) (Application database), [`src/tender_intelligence/notifications/service.py`](https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/notifications/service.py) (Notification service), [`src/tender_intelligence/verdict/service.py`](https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/verdict/service.py) (Evidence verdict)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Tender pipeline"]
  node_scheduler["Source scheduler<br/>[scheduler.py]"]
  node_coordinator["Run coordinator<br/>[coordinator.py]"]
  node_adapters["Source adapters<br/>[waho.py]"]
  node_dedup["Tender deduplication<br/>[service.py]"]
  node_acquisition["Document acquisition<br/>[service.py]"]
  node_processing["Document processing<br/>[service.py]"]
end

subgraph group_assessment["Tender assessment"]
  node_triage["AI triage<br/>[service.py]"]
  node_deadline["Deadline extraction<br/>[service.py]"]
  node_verdict["Evidence verdict<br/>[service.py]"]
  node_knowledge[("Knowledge records<br/>[knowledge.py]")]
  node_llm["LLM providers<br/>[llm.py]"]
end

subgraph group_delivery["Notifications"]
  node_notification["Notification service<br/>[service.py]"]
  node_mail["Mail providers<br/>[provider.py]"]
end

subgraph group_operations["Admin and audit"]
  node_admin["Admin API and UI<br/>[main.py]"]
  node_audit["Audit and alerts<br/>[alert_manager.py]"]
end

subgraph group_foundation["Shared foundation"]
  node_storage["Object storage<br/>[interface.py]"]
  node_database[("Application database<br/>[engine.py]")]
end

node_operator(("Operator"))
node_tender_source["Tender sources"]
node_human_recipient(("Human recipients"))

node_scheduler -->|"starts runs"| node_coordinator
node_coordinator -->|"discovers tenders"| node_adapters
node_adapters -->|"fetches listings"| node_tender_source
node_coordinator -->|"classifies listings"| node_dedup
node_coordinator -->|"acquires documents"| node_acquisition
node_acquisition -->|"stores bytes"| node_storage
node_coordinator -->|"processes documents"| node_processing
node_processing -->|"reads bytes"| node_storage
node_coordinator -->|"triages tenders"| node_triage
node_coordinator -->|"extracts deadlines"| node_deadline
node_coordinator -->|"generates verdict"| node_verdict
node_verdict -->|"reads capabilities"| node_knowledge
node_verdict -->|"requests assessment"| node_llm
node_triage -->|"requests triage"| node_llm
node_coordinator -->|"delivers outcomes"| node_notification
node_notification -->|"loads attachments"| node_storage
node_notification -->|"sends messages"| node_mail
node_mail -->|"delivers email"| node_human_recipient
node_operator -->|"manages system"| node_admin
node_admin -->|"requests runs"| node_coordinator
node_admin -->|"reads and updates"| node_database
node_audit -->|"persists alerts"| node_database
node_audit -->|"routes alerts"| node_notification
node_coordinator -->|"records run state"| node_database
node_dedup -->|"persists tender state"| node_database
node_acquisition -->|"records documents"| node_database
node_processing -->|"records extraction"| node_database
node_triage -->|"records decisions"| node_database
node_verdict -->|"persists verdicts"| node_database
node_notification -->|"manages outbox"| node_database

click node_scheduler "https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/orchestrator/scheduler.py"
click node_coordinator "https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/orchestrator/coordinator.py"
click node_adapters "https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/sources/waho.py"
click node_dedup "https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/dedup/service.py"
click node_acquisition "https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/acquisition/service.py"
click node_processing "https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/processing/service.py"
click node_triage "https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/triage/service.py"
click node_deadline "https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/deadline/service.py"
click node_verdict "https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/verdict/service.py"
click node_knowledge "https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/db/models/knowledge.py"
click node_llm "https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/interfaces/llm.py"
click node_notification "https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/notifications/service.py"
click node_mail "https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/mail/provider.py"
click node_storage "https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/storage/interface.py"
click node_database "https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/db/engine.py"
click node_admin "https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/admin/main.py"
click node_audit "https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/audit/alert_manager.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_scheduler,node_coordinator,node_adapters,node_dedup,node_acquisition,node_processing toneBlue
class node_triage,node_deadline,node_verdict,node_knowledge,node_llm toneAmber
class node_notification,node_mail toneMint
class node_admin,node_audit toneRose
class node_storage,node_database,node_operator,node_tender_source,node_human_recipient toneIndigo
```

## Components

### Tender pipeline

- [Source scheduler](https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/orchestrator/scheduler.py): `src/tender_intelligence/orchestrator/scheduler.py`
- [Run coordinator](https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/orchestrator/coordinator.py): `src/tender_intelligence/orchestrator/coordinator.py`
- [Source adapters](https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/sources/waho.py): `src/tender_intelligence/sources/waho.py`
- [Tender deduplication](https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/dedup/service.py): `src/tender_intelligence/dedup/service.py`
- [Document acquisition](https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/acquisition/service.py): `src/tender_intelligence/acquisition/service.py`
- [Document processing](https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/processing/service.py): `src/tender_intelligence/processing/service.py`

### Tender assessment

- [AI triage](https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/triage/service.py): `src/tender_intelligence/triage/service.py`
- [Deadline extraction](https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/deadline/service.py): `src/tender_intelligence/deadline/service.py`
- [Evidence verdict](https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/verdict/service.py): `src/tender_intelligence/verdict/service.py`
- [Knowledge records](https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/db/models/knowledge.py): `src/tender_intelligence/db/models/knowledge.py`
- [LLM providers](https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/interfaces/llm.py): `src/tender_intelligence/interfaces/llm.py`

### Notifications

- [Notification service](https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/notifications/service.py): `src/tender_intelligence/notifications/service.py`
- [Mail providers](https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/mail/provider.py): `src/tender_intelligence/mail/provider.py`

### Admin and audit

- [Admin API and UI](https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/admin/main.py): `src/tender_intelligence/admin/main.py`
- [Audit and alerts](https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/audit/alert_manager.py): `src/tender_intelligence/audit/alert_manager.py`

### Shared foundation

- [Object storage](https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/storage/interface.py): `src/tender_intelligence/storage/interface.py`
- [Application database](https://github.com/ife-banks/tender-intelligence/blob/main/src/tender_intelligence/db/engine.py): `src/tender_intelligence/db/engine.py`

### Other components

- **Operator**
- **Tender sources**
- **Human recipients**

## Connections

- Source scheduler → Run coordinator: starts runs
- Run coordinator → Source adapters: discovers tenders
- Source adapters → Tender sources: fetches listings
- Run coordinator → Tender deduplication: classifies listings
- Run coordinator → Document acquisition: acquires documents
- Document acquisition → Object storage: stores bytes
- Run coordinator → Document processing: processes documents
- Document processing → Object storage: reads bytes
- Run coordinator → AI triage: triages tenders
- Run coordinator → Deadline extraction: extracts deadlines
- Run coordinator → Evidence verdict: generates verdict
- Evidence verdict → Knowledge records: reads capabilities
- Evidence verdict → LLM providers: requests assessment
- AI triage → LLM providers: requests triage
- Run coordinator → Notification service: delivers outcomes
- Notification service → Object storage: loads attachments
- Notification service → Mail providers: sends messages
- Mail providers → Human recipients: delivers email
- Operator → Admin API and UI: manages system
- Admin API and UI → Run coordinator: requests runs
- Admin API and UI → Application database: reads and updates
- Audit and alerts → Application database: persists alerts
- Audit and alerts → Notification service: routes alerts
- Run coordinator → Application database: records run state
- Tender deduplication → Application database: persists tender state
- Document acquisition → Application database: records documents
- Document processing → Application database: records extraction
- AI triage → Application database: records decisions
- Evidence verdict → Application database: persists verdicts
- Notification service → Application database: manages outbox