# pedrodnt/silo-bz architecture

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

- Interactive diagram: https://gitdiagram.com/pedrodnt/silo-bz
- Repository: https://github.com/pedrodnt/silo-bz

## Overview

SILO ingests public Brazilian financial data, validates and stores it in Supabase Postgres, then exposes read-only data for people and agents. Its principal data workflow is source fetch → parse and validate → pipeline orchestration → warehouse; the read API and SDK provide a separate query path. A portfolio-diagnosis service accepts statements, queries SILO data, computes analysis, and renders reports. The README documents the ingest stages and public surfaces; some subsystem links below rely on SOURCE INDEX references rather than inspected implementation excerpts.

Main entry points: [`src/pipeline`](https://github.com/pedrodnt/silo-bz/tree/main/src/pipeline) (Ingest orchestration), [`serve/app.py`](https://github.com/pedrodnt/silo-bz/blob/main/serve/app.py) (Read API), [`src/fetchers`](https://github.com/pedrodnt/silo-bz/tree/main/src/fetchers) (Source fetchers), [`src/portfolio/server.py`](https://github.com/pedrodnt/silo-bz/blob/main/src/portfolio/server.py) (Diagnosis endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data ingestion"]
  node_fetch["Source fetchers"]
  node_parse["Parsing and validation"]
  node_pipeline["Ingest orchestration"]
  node_audit["Ingest audit<br/>[ingest_log.py]"]
end

subgraph group_warehouse["Warehouse and serving"]
  node_store["Postgres client<br/>[pg_client.py]"]
  node_db[("Supabase warehouse")]
end

subgraph group_portfolio["Portfolio diagnosis"]
  node_portfolio_server["Diagnosis endpoint<br/>[server.py]"]
  node_statement["Statement handling<br/>[statement.py]"]
  node_engine["Diagnosis engine<br/>[engine.py]"]
  node_client["Portfolio data client<br/>[client.py]"]
  node_analysis["Portfolio analysis"]
  node_report["Report rendering<br/>[render.py]"]
end

subgraph group_agent["Agent access"]
  node_mcp["SILO MCP tools<br/>[tools.ts]"]
end

subgraph group_public["Public surfaces"]
  node_api["Read API<br/>[app.py]"]
  node_catalog["API catalog<br/>[catalog.py]"]
  node_sdk["Python client<br/>[client.py]"]
  node_dashboard["Public dashboard<br/>[+layout.svelte]"]
end

node_cvm(("CVM data"))
node_b3(("B3 data"))
node_macro(("Macro data"))
node_researcher(("Researchers and readers"))
node_agent(("AI agents"))

node_cvm -->|"provides filings"| node_fetch
node_b3 -->|"provides market data"| node_fetch
node_macro -->|"provides series"| node_fetch
node_pipeline -->|"orchestrates fetch"| node_fetch
node_pipeline -->|"orchestrates parsing"| node_parse
node_parse -->|"validated rows"| node_store
node_pipeline -->|"upserts data"| node_store
node_pipeline -->|"records ingest"| node_audit
node_store -->|"writes rows"| node_db
node_db -->|"serves schema"| node_api
node_api -->|"uses catalog"| node_catalog
node_researcher -->|"queries"| node_api
node_agent -->|"uses tools"| node_mcp
node_sdk -->|"calls endpoints"| node_api
node_pipeline -->|"triggers republish"| node_dashboard
node_portfolio_server -.->|"handles input"| node_statement
node_portfolio_server -->|"runs diagnosis"| node_engine
node_engine -->|"queries data"| node_client
node_engine -->|"computes metrics"| node_analysis
node_portfolio_server -->|"renders report"| node_report
node_mcp -.->|"reads warehouse"| node_db

click node_fetch "https://github.com/pedrodnt/silo-bz/tree/main/src/fetchers"
click node_parse "https://github.com/pedrodnt/silo-bz/tree/main/src/parsers"
click node_pipeline "https://github.com/pedrodnt/silo-bz/tree/main/src/pipeline"
click node_audit "https://github.com/pedrodnt/silo-bz/blob/main/src/pipeline/ingest_log.py"
click node_store "https://github.com/pedrodnt/silo-bz/blob/main/src/store/pg_client.py"
click node_api "https://github.com/pedrodnt/silo-bz/blob/main/serve/app.py"
click node_catalog "https://github.com/pedrodnt/silo-bz/blob/main/serve/catalog.py"
click node_sdk "https://github.com/pedrodnt/silo-bz/blob/main/sdk/silo_client/client.py"
click node_dashboard "https://github.com/pedrodnt/silo-bz/blob/main/dashboard/pages/%2Blayout.svelte"
click node_mcp "https://github.com/pedrodnt/silo-bz/blob/main/supabase/functions/silo-mcp/tools.ts"
click node_portfolio_server "https://github.com/pedrodnt/silo-bz/blob/main/src/portfolio/server.py"
click node_statement "https://github.com/pedrodnt/silo-bz/blob/main/src/portfolio/statement.py"
click node_engine "https://github.com/pedrodnt/silo-bz/blob/main/src/portfolio/engine.py"
click node_client "https://github.com/pedrodnt/silo-bz/blob/main/src/portfolio/client.py"
click node_analysis "https://github.com/pedrodnt/silo-bz/tree/main/src/portfolio"
click node_report "https://github.com/pedrodnt/silo-bz/blob/main/src/portfolio/report/render.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_fetch,node_parse,node_pipeline,node_audit toneBlue
class node_store,node_db toneAmber
class node_portfolio_server,node_statement,node_engine,node_client,node_analysis,node_report toneMint
class node_mcp toneRose
class node_api,node_catalog,node_sdk,node_dashboard,node_cvm,node_b3,node_macro,node_researcher,node_agent toneIndigo
```

## Components

### Data ingestion

- [Source fetchers](https://github.com/pedrodnt/silo-bz/tree/main/src/fetchers): `src/fetchers`
- [Parsing and validation](https://github.com/pedrodnt/silo-bz/tree/main/src/parsers): `src/parsers`
- [Ingest orchestration](https://github.com/pedrodnt/silo-bz/tree/main/src/pipeline): `src/pipeline`
- [Ingest audit](https://github.com/pedrodnt/silo-bz/blob/main/src/pipeline/ingest_log.py): `src/pipeline/ingest_log.py`

### Warehouse and serving

- [Postgres client](https://github.com/pedrodnt/silo-bz/blob/main/src/store/pg_client.py): `src/store/pg_client.py`
- **Supabase warehouse**

### Portfolio diagnosis

- [Diagnosis endpoint](https://github.com/pedrodnt/silo-bz/blob/main/src/portfolio/server.py): `src/portfolio/server.py`
- [Statement handling](https://github.com/pedrodnt/silo-bz/blob/main/src/portfolio/statement.py): `src/portfolio/statement.py`
- [Diagnosis engine](https://github.com/pedrodnt/silo-bz/blob/main/src/portfolio/engine.py): `src/portfolio/engine.py`
- [Portfolio data client](https://github.com/pedrodnt/silo-bz/blob/main/src/portfolio/client.py): `src/portfolio/client.py`
- [Portfolio analysis](https://github.com/pedrodnt/silo-bz/tree/main/src/portfolio): `src/portfolio`
- [Report rendering](https://github.com/pedrodnt/silo-bz/blob/main/src/portfolio/report/render.py): `src/portfolio/report/render.py`

### Agent access

- [SILO MCP tools](https://github.com/pedrodnt/silo-bz/blob/main/supabase/functions/silo-mcp/tools.ts): `supabase/functions/silo-mcp/tools.ts`

### Public surfaces

- [Read API](https://github.com/pedrodnt/silo-bz/blob/main/serve/app.py): `serve/app.py`
- [API catalog](https://github.com/pedrodnt/silo-bz/blob/main/serve/catalog.py): `serve/catalog.py`
- [Python client](https://github.com/pedrodnt/silo-bz/blob/main/sdk/silo_client/client.py): `sdk/silo_client/client.py`
- [Public dashboard](https://github.com/pedrodnt/silo-bz/blob/main/dashboard/pages/%2Blayout.svelte): `dashboard/pages/+layout.svelte`

### Other components

- **CVM data**
- **B3 data**
- **Macro data**
- **Researchers and readers**
- **AI agents**

## Connections

- CVM data → Source fetchers: provides filings
- B3 data → Source fetchers: provides market data
- Macro data → Source fetchers: provides series
- Ingest orchestration → Source fetchers: orchestrates fetch (evidence: `src/pipeline/cvm_pipeline.py`)
- Ingest orchestration → Parsing and validation: orchestrates parsing (evidence: `src/pipeline/cvm_pipeline.py`)
- Parsing and validation → Postgres client: validated rows
- Ingest orchestration → Postgres client: upserts data (evidence: `src/pipeline/cvm_pipeline.py`)
- Ingest orchestration → Ingest audit: records ingest (evidence: `src/pipeline/ingest_log.py`)
- Postgres client → Supabase warehouse: writes rows
- Supabase warehouse → Read API: serves schema (evidence: `serve/app.py`)
- Read API → API catalog: uses catalog (evidence: `serve/app.py`)
- Researchers and readers → Read API: queries
- AI agents → SILO MCP tools: uses tools
- Python client → Read API: calls endpoints (evidence: `sdk/silo_client/client.py`)
- Ingest orchestration → Public dashboard: triggers republish
- Diagnosis endpoint → Statement handling: handles input (evidence: `src/portfolio/server.py`)
- Diagnosis endpoint → Diagnosis engine: runs diagnosis (evidence: `src/portfolio/server.py`)
- Diagnosis engine → Portfolio data client: queries data (evidence: `src/portfolio/engine.py`)
- Diagnosis engine → Portfolio analysis: computes metrics (evidence: `src/portfolio/engine.py`)
- Diagnosis endpoint → Report rendering: renders report (evidence: `src/portfolio/server.py`)
- SILO MCP tools → Supabase warehouse: reads warehouse
