# alan-fdez/compass architecture

> Architecture diagram of the GitHub repository alan-fdez/compass, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alan-fdez/compass
- Repository: https://github.com/alan-fdez/compass

## Overview

Compass is a Spanish public-tender radar: it ingests PLACSP notices, filters and ranks them for a company profile, then analyzes a selected tender’s PCAP on demand and computes a cited bid-eligibility verdict. The graph preserves the README’s major stages and product capabilities. Some matching, API, and frontend relationships are documented in the README but their source was not sampled; those links cite that documentation rather than implying direct calls between uninspected modules.

Main entry points: [`backend/src/compass/api/router.py`](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/api/router.py) (Route registry), [`backend/src/compass/api/routes/analysis.py`](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/api/routes/analysis.py) (Analysis endpoints), [`backend/src/compass/analysis/graph.py`](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/analysis/graph.py) (Extraction graph), [`backend/src/compass/matching/fusion.py`](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/matching/fusion.py) (Hybrid ranking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Dashboard"]
  node_dashboard["Tender dashboard<br/>[page.tsx]"]
  node_profile["Company profile<br/>[page.tsx]"]
  node_tender_detail["Tender detail<br/>[page.tsx]"]
  node_match_views["Match views<br/>[MatchList.tsx]"]
  node_analysis_panel["Analysis panel<br/>[AnalysisPanel.tsx]"]
  node_polling["Analysis polling"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_api["API"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_api_router["Route registry<br/>[router.py]"]
  node_analysis_route["Analysis endpoints<br/>[analysis.py]"]
  node_matches_route["Match endpoints<br/>[matches.py]"]
  node_profile_route["Provider endpoints<br/>[providers.py]"]
  node_backfill_route["Backfill endpoint<br/>[ingestion.py]"]
end

subgraph group_ingest["Tender ingestion"]
  node_ingestion_task["Ingestion tasks<br/>[tasks.py]"]
  node_daily_ingestion["Daily ingestion<br/>[daily_ingestion.py]"]
  node_tender_store[("Tender store<br/>[repository.py]")]
  node_tender_model["Tender records<br/>[models.py]"]
end

subgraph group_matching["Matching"]
  node_matching["Hybrid ranking<br/>[fusion.py]"]
  node_matching_store["Matching queries<br/>[repository.py]"]
  node_embedding["Embedding generation<br/>[embeddings.py]"]
end

subgraph group_analysis["Pliego analysis"]
  node_analysis_task["Analysis task<br/>[tasks.py]"]
  node_analysis_graph{{"Extraction graph<br/>[graph.py]"}}
  node_document["PCAP handling<br/>[document.py]"]
  node_openrouter["LLM provider<br/>[openrouter.py]"]
  node_verification["Citation checks<br/>[verification.py]"]
  node_verdict["Eligibility verdict<br/>[verdict.py]"]
  node_analysis_store[("Analysis records<br/>[repository.py]")]
end

node_user(("Company user"))
node_placsp["PLACSP feed"]
node_langfuse["Langfuse tracing"]

node_user -->|"views matches"| node_dashboard
node_user -->|"sets profile"| node_profile
node_user -->|"opens tender"| node_tender_detail
node_tender_detail -->|"shows analysis"| node_analysis_panel
node_analysis_panel -->|"requests status"| node_polling
node_dashboard -->|"loads matches"| node_api_client
node_profile -->|"saves profile"| node_api_client
node_analysis_panel -->|"starts analysis"| node_api_client
node_polling -->|"polls status"| node_api_client
node_api_client -->|"calls API"| node_api_app
node_api_app -->|"mounts routes"| node_api_router
node_api_router -->|"registers"| node_analysis_route
node_api_router -->|"registers"| node_matches_route
node_api_router -->|"registers"| node_profile_route
node_api_router -->|"registers"| node_backfill_route
node_backfill_route -->|"queues backfill"| node_ingestion_task
node_placsp -->|"provides notices"| node_daily_ingestion
node_ingestion_task -->|"runs"| node_daily_ingestion
node_daily_ingestion -->|"upserts tenders"| node_tender_store
node_tender_store -->|"persists"| node_tender_model
node_tender_model -->|"supplies corpus"| node_matching
node_profile_route -->|"supplies profile"| node_matching
node_matches_route -->|"requests ranking"| node_matching
node_matching -->|"queries candidates"| node_matching_store
node_matching -->|"returns ranked matches"| node_dashboard
node_ingestion_task -->|"queues embeddings"| node_embedding
node_embedding -->|"writes vectors"| node_tender_model
node_analysis_route -->|"queues analysis"| node_analysis_task
node_analysis_task -->|"runs extraction"| node_analysis_graph
node_analysis_task -->|"downloads PCAP"| node_document
node_analysis_graph -->|"reads document"| node_document
node_analysis_graph -->|"calls model"| node_openrouter
node_analysis_graph -->|"checks citations"| node_verification
node_analysis_task -->|"loads and saves"| node_analysis_store
node_analysis_route -->|"computes eligibility"| node_verdict
node_analysis_route -->|"reads analysis"| node_analysis_store
node_analysis_route -->|"returns cited result"| node_tender_detail
node_analysis_graph -.->|"traces calls"| node_langfuse

click node_dashboard "https://github.com/alan-fdez/compass/blob/main/frontend/src/app/page.tsx"
click node_profile "https://github.com/alan-fdez/compass/blob/main/frontend/src/app/perfil/page.tsx"
click node_tender_detail "https://github.com/alan-fdez/compass/blob/main/frontend/src/app/tenders/%5B...expediente%5D/page.tsx"
click node_match_views "https://github.com/alan-fdez/compass/blob/main/frontend/src/components/matches/MatchList.tsx"
click node_analysis_panel "https://github.com/alan-fdez/compass/blob/main/frontend/src/components/analysis/AnalysisPanel.tsx"
click node_polling "https://github.com/alan-fdez/compass/blob/main/frontend/src/hooks/useAnalysisPolling.ts"
click node_api_client "https://github.com/alan-fdez/compass/blob/main/frontend/src/lib/api/client.ts"
click node_api_app "https://github.com/alan-fdez/compass/blob/main/backend/src/compass/main.py"
click node_api_router "https://github.com/alan-fdez/compass/blob/main/backend/src/compass/api/router.py"
click node_analysis_route "https://github.com/alan-fdez/compass/blob/main/backend/src/compass/api/routes/analysis.py"
click node_matches_route "https://github.com/alan-fdez/compass/blob/main/backend/src/compass/api/routes/matches.py"
click node_profile_route "https://github.com/alan-fdez/compass/blob/main/backend/src/compass/api/routes/providers.py"
click node_backfill_route "https://github.com/alan-fdez/compass/blob/main/backend/src/compass/api/routes/ingestion.py"
click node_ingestion_task "https://github.com/alan-fdez/compass/blob/main/backend/src/compass/ingestion/tasks.py"
click node_daily_ingestion "https://github.com/alan-fdez/compass/blob/main/backend/src/compass/ingestion/daily_ingestion.py"
click node_tender_store "https://github.com/alan-fdez/compass/blob/main/backend/src/compass/tenders/repository.py"
click node_tender_model "https://github.com/alan-fdez/compass/blob/main/backend/src/compass/tenders/models.py"
click node_matching "https://github.com/alan-fdez/compass/blob/main/backend/src/compass/matching/fusion.py"
click node_matching_store "https://github.com/alan-fdez/compass/blob/main/backend/src/compass/matching/repository.py"
click node_embedding "https://github.com/alan-fdez/compass/blob/main/backend/src/compass/matching/embeddings.py"
click node_analysis_task "https://github.com/alan-fdez/compass/blob/main/backend/src/compass/analysis/tasks.py"
click node_analysis_graph "https://github.com/alan-fdez/compass/blob/main/backend/src/compass/analysis/graph.py"
click node_document "https://github.com/alan-fdez/compass/blob/main/backend/src/compass/analysis/document.py"
click node_openrouter "https://github.com/alan-fdez/compass/blob/main/backend/src/compass/analysis/openrouter.py"
click node_verification "https://github.com/alan-fdez/compass/blob/main/backend/src/compass/analysis/verification.py"
click node_verdict "https://github.com/alan-fdez/compass/blob/main/backend/src/compass/analysis/verdict.py"
click node_analysis_store "https://github.com/alan-fdez/compass/blob/main/backend/src/compass/analysis/repository.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_dashboard,node_profile,node_tender_detail,node_match_views,node_analysis_panel,node_polling,node_api_client,node_user toneBlue
class node_api_app,node_api_router,node_analysis_route,node_matches_route,node_profile_route,node_backfill_route toneAmber
class node_ingestion_task,node_daily_ingestion,node_tender_store,node_tender_model toneMint
class node_matching,node_matching_store,node_embedding toneRose
class node_analysis_task,node_analysis_graph,node_document,node_openrouter,node_verification,node_verdict,node_analysis_store,node_placsp,node_langfuse toneIndigo
```

## Components

### Dashboard

- [Tender dashboard](https://github.com/alan-fdez/compass/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Company profile](https://github.com/alan-fdez/compass/blob/main/frontend/src/app/perfil/page.tsx): `frontend/src/app/perfil/page.tsx`
- [Tender detail](https://github.com/alan-fdez/compass/blob/main/frontend/src/app/tenders/%5B...expediente%5D/page.tsx): `frontend/src/app/tenders/[...expediente]/page.tsx`
- [Match views](https://github.com/alan-fdez/compass/blob/main/frontend/src/components/matches/MatchList.tsx): `frontend/src/components/matches/MatchList.tsx`
- [Analysis panel](https://github.com/alan-fdez/compass/blob/main/frontend/src/components/analysis/AnalysisPanel.tsx): `frontend/src/components/analysis/AnalysisPanel.tsx`
- [Analysis polling](https://github.com/alan-fdez/compass/blob/main/frontend/src/hooks/useAnalysisPolling.ts): `frontend/src/hooks/useAnalysisPolling.ts`
- [API client](https://github.com/alan-fdez/compass/blob/main/frontend/src/lib/api/client.ts): `frontend/src/lib/api/client.ts`

### API

- [FastAPI app](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/main.py): `backend/src/compass/main.py`
- [Route registry](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/api/router.py): `backend/src/compass/api/router.py`
- [Analysis endpoints](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/api/routes/analysis.py): `backend/src/compass/api/routes/analysis.py`
- [Match endpoints](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/api/routes/matches.py): `backend/src/compass/api/routes/matches.py`
- [Provider endpoints](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/api/routes/providers.py): `backend/src/compass/api/routes/providers.py`
- [Backfill endpoint](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/api/routes/ingestion.py): `backend/src/compass/api/routes/ingestion.py`

### Tender ingestion

- [Ingestion tasks](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/ingestion/tasks.py): `backend/src/compass/ingestion/tasks.py`
- [Daily ingestion](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/ingestion/daily_ingestion.py): `backend/src/compass/ingestion/daily_ingestion.py`
- [Tender store](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/tenders/repository.py): `backend/src/compass/tenders/repository.py`
- [Tender records](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/tenders/models.py): `backend/src/compass/tenders/models.py`

### Matching

- [Hybrid ranking](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/matching/fusion.py): `backend/src/compass/matching/fusion.py`
- [Matching queries](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/matching/repository.py): `backend/src/compass/matching/repository.py`
- [Embedding generation](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/matching/embeddings.py): `backend/src/compass/matching/embeddings.py`

### Pliego analysis

- [Analysis task](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/analysis/tasks.py): `backend/src/compass/analysis/tasks.py`
- [Extraction graph](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/analysis/graph.py): `backend/src/compass/analysis/graph.py`
- [PCAP handling](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/analysis/document.py): `backend/src/compass/analysis/document.py`
- [LLM provider](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/analysis/openrouter.py): `backend/src/compass/analysis/openrouter.py`
- [Citation checks](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/analysis/verification.py): `backend/src/compass/analysis/verification.py`
- [Eligibility verdict](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/analysis/verdict.py): `backend/src/compass/analysis/verdict.py`
- [Analysis records](https://github.com/alan-fdez/compass/blob/main/backend/src/compass/analysis/repository.py): `backend/src/compass/analysis/repository.py`

### Other components

- **Company user**
- **PLACSP feed**
- **Langfuse tracing**

## Connections

- Company user → Tender dashboard: views matches
- Company user → Company profile: sets profile
- Company user → Tender detail: opens tender
- Tender detail → Analysis panel: shows analysis
- Analysis panel → Analysis polling: requests status
- Tender dashboard → API client: loads matches
- Company profile → API client: saves profile
- Analysis panel → API client: starts analysis
- Analysis polling → API client: polls status
- API client → FastAPI app: calls API
- FastAPI app → Route registry: mounts routes (evidence: `backend/src/compass/main.py`)
- Route registry → Analysis endpoints: registers (evidence: `backend/src/compass/api/router.py`)
- Route registry → Match endpoints: registers (evidence: `backend/src/compass/api/router.py`)
- Route registry → Provider endpoints: registers (evidence: `backend/src/compass/api/router.py`)
- Route registry → Backfill endpoint: registers (evidence: `backend/src/compass/api/router.py`)
- Backfill endpoint → Ingestion tasks: queues backfill (evidence: `backend/src/compass/api/routes/ingestion.py`)
- PLACSP feed → Daily ingestion: provides notices
- Ingestion tasks → Daily ingestion: runs (evidence: `backend/src/compass/ingestion/tasks.py`)
- Daily ingestion → Tender store: upserts tenders (evidence: `backend/src/compass/ingestion/daily_ingestion.py`)
- Tender store → Tender records: persists (evidence: `backend/src/compass/tenders/repository.py`)
- Tender records → Hybrid ranking: supplies corpus
- Provider endpoints → Hybrid ranking: supplies profile
- Match endpoints → Hybrid ranking: requests ranking
- Hybrid ranking → Matching queries: queries candidates
- Hybrid ranking → Tender dashboard: returns ranked matches
- Ingestion tasks → Embedding generation: queues embeddings (evidence: `backend/src/compass/ingestion/tasks.py`)
- Embedding generation → Tender records: writes vectors (evidence: `backend/src/compass/matching/tasks.py`)
- Analysis endpoints → Analysis task: queues analysis (evidence: `backend/src/compass/api/routes/analysis.py`)
- Analysis task → Extraction graph: runs extraction (evidence: `backend/src/compass/analysis/tasks.py`)
- Analysis task → PCAP handling: downloads PCAP (evidence: `backend/src/compass/analysis/tasks.py`)
- Extraction graph → PCAP handling: reads document (evidence: `backend/src/compass/analysis/graph.py`)
- Extraction graph → LLM provider: calls model (evidence: `backend/src/compass/analysis/graph.py`)
- Extraction graph → Citation checks: checks citations (evidence: `backend/src/compass/analysis/graph.py`)
- Analysis task → Analysis records: loads and saves (evidence: `backend/src/compass/analysis/tasks.py`)
- Analysis endpoints → Eligibility verdict: computes eligibility (evidence: `backend/src/compass/api/routes/analysis.py`)
- Analysis endpoints → Analysis records: reads analysis (evidence: `backend/src/compass/api/routes/analysis.py`)
- Analysis endpoints → Tender detail: returns cited result
- Extraction graph → Langfuse tracing: traces calls
