spb/company-atlas

1# Company Atlas — The Live Atlas of Global Companies23**https://www.company-atlas.co** · a continuously updated corporate observation network.45Company Atlas attaches persistent public-web sensors to companies (homepage, careers and job boards, newsroom, pricing, products,6leadership, locations, docs, changelog, investor relations, legal pages, feeds, sitemaps…). Every sensor produces observations;7observations become historical snapshots; snapshots produce block-level changes; meaningful changes become structured, carefully8worded events; events become metrics (Activity Score, Hiring Momentum, Product Velocity, AI Adoption, Corporate Change Index, Global9Corporate Activity Index) and signals. Nothing historical is ever overwritten. **The accumulated history is the product.**1011| | |12|---|---|13| Spec | `docs/PRODUCT-SPEC.md` (200 sections) · repo guide `CLAUDE.md` |14| Architecture | `docs/ARCHITECTURE.md` · crawl `docs/CRAWL.md` · connectors `docs/CONNECTORS.md` · events `docs/EVENT-TAXONOMY.md` · scoring `docs/SCORING.md` · LLM `docs/LLM.md` · seeds `docs/SEEDS.md` |15| API | `docs/API.md` (`/api/v1`, SSE `/api/v1/live/stream`, exports, admin) — live docs at `/api/v1/docs` |16| Web | `apps/web` (Next 16) — `docs/FRONTEND.md` |17| Deploy / ops | `docs/DEPLOY.md` · `docs/OPERATIONS.md` |1819## Stack20Python 3.12 (`src/companyatlas`, CLI `catlas`: FastAPI · SQLAlchemy Core + asyncpg · Alembic · httpx · selectolax · feedparser · zstd) ·21PostgreSQL 17 (the only stateful dependency: entities, history, `SKIP LOCKED` queue, metrics) · content-addressed object store on disk ·22Next 16 + React 19 + Tailwind v4 · optional OpenAI-compatible LLM endpoint for enrichment (MacLustr llm-api.io).2324## Quickstart25```bash26uv venv --python 3.12 .venv && uv pip install --python .venv/bin/python -e '.[dev]'27createdb -O companyatlas companyatlas            # role companyatlas/companyatlas; extensions pg_trgm + uuid-ossp28cp .env.example .env29.venv/bin/catlas migrate && .venv/bin/catlas seed   # schema + industries/countries/companies (Wikidata registry)30.venv/bin/catlas discover https://stripe.com --dry-run31.venv/bin/catlas onboard --limit 100             # discovery → sensors32.venv/bin/catlas schedule                         # crawl + intelligence loop33.venv/bin/catlas api                              # http://127.0.0.1:8371/api/v1/docs34pnpm install && pnpm dev:web                      # http://localhost:837035.venv/bin/pytest -q && .venv/bin/ruff check src tests && pnpm -r typecheck36```3738## Principles (short form)39Historical-first · raw and interpreted data kept separate · deterministic pipeline first, LLMs only as budgeted enrichment · reusable40connector families, automatic discovery · polite and lawful crawling (robots, per-domain limits, SSRF guard, never bypass challenges,41no private data) · provenance and confidence on every fact · careful language ("no longer listed", never "fired") · no magic numbers ·42mobile first-class · never fabricate.4344Contact: contact@spboucher.ai · crawler identity `CompanyAtlasBot` (see `/bot`). Hosted on MacLustr.45