# doni9480/serebra architecture

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

- Interactive diagram: https://gitdiagram.com/doni9480/serebra
- Repository: https://github.com/doni9480/serebra

## Overview

Serebra turns hiring, public GitHub, and first-party publication data into evidence-linked company intelligence and market analytics. The main path is collection or vacancy import, normalization and deduplication, factual events, period comparisons, signals, hypotheses, and weighted evidence; API and dashboards expose the results. Distinct source-specific ingestion and intelligence branches also support company comparison, market summaries and salary analysis, collector-run tracking, company consolidation, and exchange rates. The README documents several capabilities whose implementation was not sampled, so those links are documented rather than inferred from unseen code.

Main entry points: [`backend/api/routes/companies.py`](https://github.com/doni9480/serebra/blob/main/backend/api/routes/companies.py) (Company API), [`backend/services/intelligence.py`](https://github.com/doni9480/serebra/blob/main/backend/services/intelligence.py) (Hiring intelligence), [`backend/api/routes/market.py`](https://github.com/doni9480/serebra/blob/main/backend/api/routes/market.py) (Market API), [`backend/main.py`](https://github.com/doni9480/serebra/blob/main/backend/main.py) (FastAPI runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and dashboards"]
  node_runtime["FastAPI runtime<br/>[main.py]"]
  node_company_api["Company API<br/>[companies.py]"]
  node_market_api["Market API<br/>[market.py]"]
  node_comparison_api["Comparison API<br/>[comparison.py]"]
  node_hypothesis_api["Hypothesis API<br/>[hypotheses.py]"]
  node_company_ui["Company dashboard<br/>[dashboard.js]"]
  node_market_ui["Market dashboard<br/>[market.js]"]
end

subgraph group_sources["Source collection"]
  node_devkg["DevKG collector<br/>[devkg.py]"]
  node_greenhouse["Greenhouse collector<br/>[greenhouse.py]"]
  node_github["GitHub collector<br/>[github.py]"]
  node_webfeed["RSS / Atom collector<br/>[web_feed.py]"]
end

subgraph group_ingest["Ingestion and records"]
  node_vacancy_ingest["Vacancy ingestion<br/>[ingestion.py]"]
  node_market_ingest["Market ingestion"]
  node_github_ingest["GitHub ingestion"]
  node_web_ingest["Publication ingestion<br/>[web_ingestion.py]"]
  node_normalization["Vacancy normalization<br/>[normalization.py]"]
  node_company_identity["Company identity"]
  node_consolidation["Company consolidation"]
end

subgraph group_analysis["Intelligence and analytics"]
  node_company_intel["Hiring intelligence<br/>[intelligence.py]"]
  node_github_intel["GitHub intelligence"]
  node_web_intel["Publication intelligence"]
  node_comparison["Company comparison"]
  node_market_analytics["Market analytics"]
  node_collector_runs["Collector run log<br/>[collector_runs.py]"]
end

subgraph group_persistence["Persistence"]
  node_database[("Relational store<br/>[models.py]")]
  node_db_session["Database sessions<br/>[base.py]"]
end

node_client(("API clients"))
node_feed(("External feeds"))
node_github_ext(("GitHub API"))
node_greenhouse_ext(("Greenhouse API"))

node_client -->|"requests"| node_runtime
node_runtime -->|"routes"| node_company_api
node_runtime -->|"routes"| node_market_api
node_runtime -->|"routes"| node_comparison_api
node_runtime -->|"routes"| node_hypothesis_api
node_company_api -->|"imports"| node_vacancy_ingest
node_company_api -->|"collects"| node_greenhouse
node_company_api -->|"collects"| node_github
node_company_api -->|"collects"| node_webfeed
node_company_api -->|"resolves identity"| node_consolidation
node_feed -->|"provides posts"| node_devkg
node_feed -->|"provides feeds"| node_webfeed
node_github_ext -->|"provides data"| node_github
node_greenhouse_ext -->|"provides jobs"| node_greenhouse
node_market_api -->|"collects"| node_devkg
node_market_api -->|"imports"| node_market_ingest
node_market_ingest -->|"uses snapshot"| node_devkg
node_market_ingest -->|"imports vacancies"| node_vacancy_ingest
node_market_ingest -->|"normalizes names"| node_company_identity
node_market_ingest -->|"finds identity"| node_consolidation
node_vacancy_ingest -->|"normalizes"| node_normalization
node_vacancy_ingest -->|"recalculates"| node_company_intel
node_company_api -->|"serves signals"| node_company_intel
node_github_ingest -->|"uses snapshots"| node_github
node_github_ingest -->|"recalculates"| node_github_intel
node_web_ingest -->|"uses snapshots"| node_webfeed
node_web_ingest -->|"recalculates"| node_web_intel
node_company_intel -->|"stores results"| node_database
node_github_intel -->|"contributes signals"| node_company_intel
node_web_intel -->|"contributes signals"| node_company_intel
node_company_intel -->|"stores evidence"| node_database
node_comparison_api -->|"calls"| node_comparison
node_comparison -->|"uses intelligence"| node_company_intel
node_market_api -->|"queries"| node_market_analytics
node_hypothesis_api -->|"reads hypotheses"| node_database
node_company_ui -->|"displays company data"| node_company_api
node_market_ui -->|"displays market data"| node_market_api
node_company_api -->|"records runs"| node_collector_runs
node_market_api -->|"records runs"| node_collector_runs
node_collector_runs -->|"persists runs"| node_database
node_db_session -->|"opens sessions"| node_database
node_consolidation -->|"reconciles records"| node_company_intel
node_market_api -->|"summarizes salaries"| node_market_analytics

click node_runtime "https://github.com/doni9480/serebra/blob/main/backend/main.py"
click node_company_api "https://github.com/doni9480/serebra/blob/main/backend/api/routes/companies.py"
click node_market_api "https://github.com/doni9480/serebra/blob/main/backend/api/routes/market.py"
click node_comparison_api "https://github.com/doni9480/serebra/blob/main/backend/api/routes/comparison.py"
click node_hypothesis_api "https://github.com/doni9480/serebra/blob/main/backend/api/routes/hypotheses.py"
click node_company_ui "https://github.com/doni9480/serebra/blob/main/backend/static/dashboard.js"
click node_market_ui "https://github.com/doni9480/serebra/blob/main/backend/static/market.js"
click node_devkg "https://github.com/doni9480/serebra/blob/main/backend/collectors/devkg.py"
click node_greenhouse "https://github.com/doni9480/serebra/blob/main/backend/collectors/greenhouse.py"
click node_github "https://github.com/doni9480/serebra/blob/main/backend/collectors/github.py"
click node_webfeed "https://github.com/doni9480/serebra/blob/main/backend/collectors/web_feed.py"
click node_vacancy_ingest "https://github.com/doni9480/serebra/blob/main/backend/services/ingestion.py"
click node_market_ingest "https://github.com/doni9480/serebra/blob/main/backend/services/market_ingestion.py"
click node_github_ingest "https://github.com/doni9480/serebra/blob/main/backend/services/github_ingestion.py"
click node_web_ingest "https://github.com/doni9480/serebra/blob/main/backend/services/web_ingestion.py"
click node_normalization "https://github.com/doni9480/serebra/blob/main/backend/services/normalization.py"
click node_company_identity "https://github.com/doni9480/serebra/blob/main/backend/services/company_normalization.py"
click node_consolidation "https://github.com/doni9480/serebra/blob/main/backend/services/company_consolidation.py"
click node_company_intel "https://github.com/doni9480/serebra/blob/main/backend/services/intelligence.py"
click node_github_intel "https://github.com/doni9480/serebra/blob/main/backend/services/github_intelligence.py"
click node_web_intel "https://github.com/doni9480/serebra/blob/main/backend/services/web_intelligence.py"
click node_comparison "https://github.com/doni9480/serebra/blob/main/backend/services/company_comparison.py"
click node_market_analytics "https://github.com/doni9480/serebra/blob/main/backend/services/market_analytics.py"
click node_collector_runs "https://github.com/doni9480/serebra/blob/main/backend/services/collector_runs.py"
click node_database "https://github.com/doni9480/serebra/blob/main/backend/db/models.py"
click node_db_session "https://github.com/doni9480/serebra/blob/main/backend/db/base.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_runtime,node_company_api,node_market_api,node_comparison_api,node_hypothesis_api,node_company_ui,node_market_ui,node_client toneBlue
class node_devkg,node_greenhouse,node_github,node_webfeed toneAmber
class node_vacancy_ingest,node_market_ingest,node_github_ingest,node_web_ingest,node_normalization,node_company_identity,node_consolidation,node_github_ext,node_greenhouse_ext toneMint
class node_company_intel,node_github_intel,node_web_intel,node_comparison,node_market_analytics,node_collector_runs toneRose
class node_database,node_db_session,node_feed toneIndigo
```

## Components

### API and dashboards

- [FastAPI runtime](https://github.com/doni9480/serebra/blob/main/backend/main.py): `backend/main.py`
- [Company API](https://github.com/doni9480/serebra/blob/main/backend/api/routes/companies.py): `backend/api/routes/companies.py`
- [Market API](https://github.com/doni9480/serebra/blob/main/backend/api/routes/market.py): `backend/api/routes/market.py`
- [Comparison API](https://github.com/doni9480/serebra/blob/main/backend/api/routes/comparison.py): `backend/api/routes/comparison.py`
- [Hypothesis API](https://github.com/doni9480/serebra/blob/main/backend/api/routes/hypotheses.py): `backend/api/routes/hypotheses.py`
- [Company dashboard](https://github.com/doni9480/serebra/blob/main/backend/static/dashboard.js): `backend/static/dashboard.js`
- [Market dashboard](https://github.com/doni9480/serebra/blob/main/backend/static/market.js): `backend/static/market.js`

### Source collection

- [DevKG collector](https://github.com/doni9480/serebra/blob/main/backend/collectors/devkg.py): `backend/collectors/devkg.py`
- [Greenhouse collector](https://github.com/doni9480/serebra/blob/main/backend/collectors/greenhouse.py): `backend/collectors/greenhouse.py`
- [GitHub collector](https://github.com/doni9480/serebra/blob/main/backend/collectors/github.py): `backend/collectors/github.py`
- [RSS / Atom collector](https://github.com/doni9480/serebra/blob/main/backend/collectors/web_feed.py): `backend/collectors/web_feed.py`

### Ingestion and records

- [Vacancy ingestion](https://github.com/doni9480/serebra/blob/main/backend/services/ingestion.py): `backend/services/ingestion.py`
- [Market ingestion](https://github.com/doni9480/serebra/blob/main/backend/services/market_ingestion.py): `backend/services/market_ingestion.py`
- [GitHub ingestion](https://github.com/doni9480/serebra/blob/main/backend/services/github_ingestion.py): `backend/services/github_ingestion.py`
- [Publication ingestion](https://github.com/doni9480/serebra/blob/main/backend/services/web_ingestion.py): `backend/services/web_ingestion.py`
- [Vacancy normalization](https://github.com/doni9480/serebra/blob/main/backend/services/normalization.py): `backend/services/normalization.py`
- [Company identity](https://github.com/doni9480/serebra/blob/main/backend/services/company_normalization.py): `backend/services/company_normalization.py`
- [Company consolidation](https://github.com/doni9480/serebra/blob/main/backend/services/company_consolidation.py): `backend/services/company_consolidation.py`

### Intelligence and analytics

- [Hiring intelligence](https://github.com/doni9480/serebra/blob/main/backend/services/intelligence.py): `backend/services/intelligence.py`
- [GitHub intelligence](https://github.com/doni9480/serebra/blob/main/backend/services/github_intelligence.py): `backend/services/github_intelligence.py`
- [Publication intelligence](https://github.com/doni9480/serebra/blob/main/backend/services/web_intelligence.py): `backend/services/web_intelligence.py`
- [Company comparison](https://github.com/doni9480/serebra/blob/main/backend/services/company_comparison.py): `backend/services/company_comparison.py`
- [Market analytics](https://github.com/doni9480/serebra/blob/main/backend/services/market_analytics.py): `backend/services/market_analytics.py`
- [Collector run log](https://github.com/doni9480/serebra/blob/main/backend/services/collector_runs.py): `backend/services/collector_runs.py`

### Persistence

- [Relational store](https://github.com/doni9480/serebra/blob/main/backend/db/models.py): `backend/db/models.py`
- [Database sessions](https://github.com/doni9480/serebra/blob/main/backend/db/base.py): `backend/db/base.py`

### Other components

- **API clients**
- **External feeds**
- **GitHub API**
- **Greenhouse API**

## Connections

- API clients → FastAPI runtime: requests
- FastAPI runtime → Company API: routes (evidence: `backend/main.py`)
- FastAPI runtime → Market API: routes (evidence: `backend/main.py`)
- FastAPI runtime → Comparison API: routes (evidence: `backend/main.py`)
- FastAPI runtime → Hypothesis API: routes (evidence: `backend/main.py`)
- Company API → Vacancy ingestion: imports (evidence: `backend/api/routes/companies.py`)
- Company API → Greenhouse collector: collects (evidence: `backend/api/routes/companies.py`)
- Company API → GitHub collector: collects (evidence: `backend/api/routes/companies.py`)
- Company API → RSS / Atom collector: collects (evidence: `backend/api/routes/companies.py`)
- Company API → Company consolidation: resolves identity (evidence: `backend/api/routes/companies.py`)
- External feeds → DevKG collector: provides posts
- External feeds → RSS / Atom collector: provides feeds
- GitHub API → GitHub collector: provides data
- Greenhouse API → Greenhouse collector: provides jobs
- Market API → DevKG collector: collects (evidence: `backend/api/routes/market.py`)
- Market API → Market ingestion: imports (evidence: `backend/api/routes/market.py`)
- Market ingestion → DevKG collector: uses snapshot (evidence: `backend/services/market_ingestion.py`)
- Market ingestion → Vacancy ingestion: imports vacancies (evidence: `backend/services/market_ingestion.py`)
- Market ingestion → Company identity: normalizes names (evidence: `backend/services/market_ingestion.py`)
- Market ingestion → Company consolidation: finds identity (evidence: `backend/services/market_ingestion.py`)
- Vacancy ingestion → Vacancy normalization: normalizes (evidence: `backend/services/ingestion.py`)
- Vacancy ingestion → Hiring intelligence: recalculates (evidence: `backend/services/ingestion.py`)
- Company API → Hiring intelligence: serves signals (evidence: `backend/api/routes/companies.py`)
- GitHub ingestion → GitHub collector: uses snapshots (evidence: `backend/services/github_ingestion.py`)
- GitHub ingestion → GitHub intelligence: recalculates (evidence: `backend/services/github_ingestion.py`)
- Publication ingestion → RSS / Atom collector: uses snapshots (evidence: `backend/services/web_ingestion.py`)
- Publication ingestion → Publication intelligence: recalculates (evidence: `backend/services/web_ingestion.py`)
- Hiring intelligence → Relational store: stores results (evidence: `backend/services/intelligence.py`)
- GitHub intelligence → Hiring intelligence: contributes signals (evidence: `backend/services/github_intelligence.py`)
- Publication intelligence → Hiring intelligence: contributes signals (evidence: `backend/services/web_intelligence.py`)
- Hiring intelligence → Relational store: stores evidence (evidence: `backend/services/intelligence.py`)
- Comparison API → Company comparison: calls (evidence: `backend/api/routes/comparison.py`)
- Company comparison → Hiring intelligence: uses intelligence (evidence: `backend/services/company_comparison.py`)
- Market API → Market analytics: queries (evidence: `backend/api/routes/market.py`)
- Hypothesis API → Relational store: reads hypotheses (evidence: `backend/api/routes/hypotheses.py`)
- Company dashboard → Company API: displays company data
- Market dashboard → Market API: displays market data
- Company API → Collector run log: records runs (evidence: `backend/api/routes/companies.py`)
- Market API → Collector run log: records runs (evidence: `backend/api/routes/market.py`)
- Collector run log → Relational store: persists runs (evidence: `backend/services/collector_runs.py`)
- Database sessions → Relational store: opens sessions (evidence: `backend/db/base.py`)
- Company consolidation → Hiring intelligence: reconciles records (evidence: `backend/services/company_consolidation.py`)
- Market API → Market analytics: summarizes salaries (evidence: `backend/api/routes/market.py`)
