# afjaramillo97/sobreplano architecture

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

- Interactive diagram: https://gitdiagram.com/afjaramillo97/sobreplano
- Repository: https://github.com/afjaramillo97/sobreplano

## Overview

Sobreplano is a Colombian off-plan housing catalog: it collects daily project prices, exposes searchable listings and price histories, and offers a conversational advisor over that catalog. The main collection workflow is scheduled or manually initiated scraping, followed by page parsing, structured extraction, validation, and append-only price recording. API routes serve catalog queries and advisor conversations; the advisor uses tools for search, comparison, and financial simulations. Evaluation modules measure advisor and extraction quality. Some subsystem links are based on README descriptions because their implementation files were not sampled.

Main entry points: [`src/sobreplano/application/scrape_developer.py`](https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/application/scrape_developer.py) (Scrape workflow), [`src/sobreplano/infrastructure/db/models.py`](https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/db/models.py) (Postgres database), [`src/sobreplano/interface/api/routes/projects.py`](https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/interface/api/routes/projects.py) (Project endpoints), [`src/sobreplano/infrastructure/advisor/tools.py`](https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/advisor/tools.py) (Advisor tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Price collection"]
  node_scrape_run["Scrape workflow"]
  node_site_parsers["Site parsers"]
  node_page_fetch["Polite fetching<br/>[http_fetcher.py]"]
  node_extraction["LLM extraction"]
  node_llm_providers["LLM providers<br/>[providers.py]"]
  node_price_recording["Price recording"]
  node_raw_store["Raw page storage<br/>[raw_store.py]"]
end

subgraph group_catalog["Catalog and API"]
  node_catalog_domain["Catalog rules<br/>[catalog.py]"]
  node_pricing_domain["Price history rules<br/>[pricing.py]"]
  node_listing_query["Listing queries"]
  node_catalog_repository["Catalog repository"]
  node_price_repository["Price repository"]
  node_database[("Postgres database<br/>[models.py]")]
  node_api["FastAPI application<br/>[main.py]"]
  node_project_routes["Project endpoints<br/>[projects.py]"]
end

subgraph group_advisor["AI advisor"]
  node_advisor_routes["Advisor endpoint<br/>[advisor.py]"]
  node_advisor_engine["LangGraph advisor"]
  node_advisor_tools["Advisor tools<br/>[tools.py]"]
  node_finance["Financial simulations<br/>[finance.py]"]
end

subgraph group_quality["Quality evaluation"]
  node_evals["Quality evaluations"]
end

node_scheduler(("Scrape initiator"))
node_developer_sites(("Developer websites"))
node_buyer(("Home buyer"))

node_scheduler -.->|"starts run"| node_scrape_run
node_scrape_run -.->|"fetches pages"| node_page_fetch
node_page_fetch -.->|"requests pages"| node_developer_sites
node_scrape_run -.->|"parses pages"| node_site_parsers
node_scrape_run -.->|"extracts data"| node_extraction
node_llm_providers -->|"builds extractor"| node_extraction
node_scrape_run -.->|"stores raw pages"| node_raw_store
node_scrape_run -->|"records prices"| node_price_recording
node_scrape_run -->|"uses entities"| node_catalog_domain
node_scrape_run -->|"uses price rules"| node_pricing_domain
node_price_recording -->|"validates observations"| node_pricing_domain
node_scrape_run -.->|"persists history"| node_database
node_catalog_repository -->|"reads and writes"| node_database
node_price_repository -->|"reads and writes"| node_database
node_api -->|"registers routes"| node_project_routes
node_api -->|"registers routes"| node_advisor_routes
node_project_routes -.->|"serves listings"| node_listing_query
node_listing_query -->|"queries catalog"| node_database
node_project_routes -->|"uses catalog types"| node_catalog_domain
node_buyer -->|"searches homes"| node_api
node_buyer -->|"asks advisor"| node_advisor_routes
node_advisor_routes -.->|"runs conversation"| node_advisor_engine
node_advisor_engine -->|"dispatches tools"| node_advisor_tools
node_advisor_tools -->|"simulates returns"| node_finance
node_advisor_tools -.->|"searches catalog"| node_listing_query
node_evals -.->|"evaluates answers"| node_advisor_engine
node_evals -.->|"evaluates extraction"| node_extraction

click node_scrape_run "https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/application/scrape_developer.py"
click node_site_parsers "https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/scraping/constructora_capital.py"
click node_page_fetch "https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/scraping/http_fetcher.py"
click node_extraction "https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/scraping/openai_compatible_extractor.py"
click node_llm_providers "https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/llm/providers.py"
click node_price_recording "https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/application/record_price_observation.py"
click node_raw_store "https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/scraping/raw_store.py"
click node_catalog_domain "https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/domain/catalog.py"
click node_pricing_domain "https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/domain/pricing.py"
click node_listing_query "https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/db/project_listing_query.py"
click node_catalog_repository "https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/db/catalog_repository.py"
click node_price_repository "https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/db/price_observation_repository.py"
click node_database "https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/db/models.py"
click node_api "https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/interface/api/main.py"
click node_project_routes "https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/interface/api/routes/projects.py"
click node_advisor_routes "https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/interface/api/routes/advisor.py"
click node_advisor_engine "https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/advisor/langgraph_advisor.py"
click node_advisor_tools "https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/advisor/tools.py"
click node_finance "https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/domain/finance.py"
click node_evals "https://github.com/afjaramillo97/sobreplano/tree/main/src/sobreplano/evals"

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_scrape_run,node_site_parsers,node_page_fetch,node_extraction,node_llm_providers,node_price_recording,node_raw_store toneBlue
class node_catalog_domain,node_pricing_domain,node_listing_query,node_catalog_repository,node_price_repository,node_database,node_api,node_project_routes toneAmber
class node_advisor_routes,node_advisor_engine,node_advisor_tools,node_finance toneMint
class node_evals toneRose
class node_scheduler,node_developer_sites,node_buyer toneIndigo
```

## Components

### Price collection

- [Scrape workflow](https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/application/scrape_developer.py): `src/sobreplano/application/scrape_developer.py`
- [Site parsers](https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/scraping/constructora_capital.py): `src/sobreplano/infrastructure/scraping/constructora_capital.py`
- [Polite fetching](https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/scraping/http_fetcher.py): `src/sobreplano/infrastructure/scraping/http_fetcher.py`
- [LLM extraction](https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/scraping/openai_compatible_extractor.py): `src/sobreplano/infrastructure/scraping/openai_compatible_extractor.py`
- [LLM providers](https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/llm/providers.py): `src/sobreplano/infrastructure/llm/providers.py`
- [Price recording](https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/application/record_price_observation.py): `src/sobreplano/application/record_price_observation.py`
- [Raw page storage](https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/scraping/raw_store.py): `src/sobreplano/infrastructure/scraping/raw_store.py`

### Catalog and API

- [Catalog rules](https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/domain/catalog.py): `src/sobreplano/domain/catalog.py`
- [Price history rules](https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/domain/pricing.py): `src/sobreplano/domain/pricing.py`
- [Listing queries](https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/db/project_listing_query.py): `src/sobreplano/infrastructure/db/project_listing_query.py`
- [Catalog repository](https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/db/catalog_repository.py): `src/sobreplano/infrastructure/db/catalog_repository.py`
- [Price repository](https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/db/price_observation_repository.py): `src/sobreplano/infrastructure/db/price_observation_repository.py`
- [Postgres database](https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/db/models.py): `src/sobreplano/infrastructure/db/models.py`
- [FastAPI application](https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/interface/api/main.py): `src/sobreplano/interface/api/main.py`
- [Project endpoints](https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/interface/api/routes/projects.py): `src/sobreplano/interface/api/routes/projects.py`

### AI advisor

- [Advisor endpoint](https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/interface/api/routes/advisor.py): `src/sobreplano/interface/api/routes/advisor.py`
- [LangGraph advisor](https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/advisor/langgraph_advisor.py): `src/sobreplano/infrastructure/advisor/langgraph_advisor.py`
- [Advisor tools](https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/infrastructure/advisor/tools.py): `src/sobreplano/infrastructure/advisor/tools.py`
- [Financial simulations](https://github.com/afjaramillo97/sobreplano/blob/main/src/sobreplano/domain/finance.py): `src/sobreplano/domain/finance.py`

### Quality evaluation

- [Quality evaluations](https://github.com/afjaramillo97/sobreplano/tree/main/src/sobreplano/evals): `src/sobreplano/evals`

### Other components

- **Scrape initiator**
- **Developer websites**
- **Home buyer**

## Connections

- Scrape initiator → Scrape workflow: starts run (evidence: `README.md`)
- Scrape workflow → Polite fetching: fetches pages (evidence: `README.md`)
- Polite fetching → Developer websites: requests pages (evidence: `README.md`)
- Scrape workflow → Site parsers: parses pages (evidence: `README.md`)
- Scrape workflow → LLM extraction: extracts data (evidence: `README.md`)
- LLM providers → LLM extraction: builds extractor (evidence: `src/sobreplano/infrastructure/llm/providers.py`)
- Scrape workflow → Raw page storage: stores raw pages (evidence: `README.md`)
- Scrape workflow → Price recording: records prices (evidence: `src/sobreplano/application/scrape_developer.py`)
- Scrape workflow → Catalog rules: uses entities (evidence: `src/sobreplano/application/scrape_developer.py`)
- Scrape workflow → Price history rules: uses price rules (evidence: `src/sobreplano/application/scrape_developer.py`)
- Price recording → Price history rules: validates observations (evidence: `src/sobreplano/application/record_price_observation.py`)
- Scrape workflow → Postgres database: persists history (evidence: `README.md`)
- Catalog repository → Postgres database: reads and writes (evidence: `src/sobreplano/infrastructure/db/catalog_repository.py`)
- Price repository → Postgres database: reads and writes (evidence: `src/sobreplano/infrastructure/db/price_observation_repository.py`)
- FastAPI application → Project endpoints: registers routes (evidence: `src/sobreplano/interface/api/main.py`)
- FastAPI application → Advisor endpoint: registers routes (evidence: `src/sobreplano/interface/api/main.py`)
- Project endpoints → Listing queries: serves listings (evidence: `README.md`)
- Listing queries → Postgres database: queries catalog (evidence: `src/sobreplano/infrastructure/db/project_listing_query.py`)
- Project endpoints → Catalog rules: uses catalog types (evidence: `src/sobreplano/interface/api/routes/projects.py`)
- Home buyer → FastAPI application: searches homes (evidence: `README.md`)
- Home buyer → Advisor endpoint: asks advisor (evidence: `README.md`)
- Advisor endpoint → LangGraph advisor: runs conversation (evidence: `README.md`)
- LangGraph advisor → Advisor tools: dispatches tools (evidence: `src/sobreplano/infrastructure/advisor/langgraph_advisor.py`)
- Advisor tools → Financial simulations: simulates returns (evidence: `src/sobreplano/infrastructure/advisor/tools.py`)
- Advisor tools → Listing queries: searches catalog (evidence: `README.md`)
- Quality evaluations → LangGraph advisor: evaluates answers (evidence: `README.md`)
- Quality evaluations → LLM extraction: evaluates extraction (evidence: `README.md`)
