# Company Atlas — The Live Atlas of Global Companies

https://www.company-atlas.co · a continuously updated corporate observation network.

Company Atlas attaches persistent public-web sensors to companies (homepage, careers and job boards, newsroom, pricing, products, leadership, locations, docs, changelog, investor relations, legal pages, feeds, sitemaps…). Every sensor produces observations; observations become historical snapshots; snapshots produce block-level changes; meaningful changes become structured, carefully worded events; events become metrics (Activity Score, Hiring Momentum, Product Velocity, AI Adoption, Corporate Change Index, Global Corporate Activity Index) and signals. Nothing historical is ever overwritten. The accumulated history is the product.


Spec	`docs/PRODUCT-SPEC.md` (200 sections) · repo guide `CLAUDE.md`
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`
API	`docs/API.md` (`/api/v1`, SSE `/api/v1/live/stream`, exports, admin) — live docs at `/api/v1/docs`
Web	`apps/web` (Next 16) — `docs/FRONTEND.md`
Deploy / ops	`docs/DEPLOY.md` · `docs/OPERATIONS.md`

# Stack

Python 3.12 (src/companyatlas, CLI catlas: FastAPI · SQLAlchemy Core + asyncpg · Alembic · httpx · selectolax · feedparser · zstd) · PostgreSQL 17 (the only stateful dependency: entities, history, SKIP LOCKED queue, metrics) · content-addressed object store on disk · Next 16 + React 19 + Tailwind v4 · optional OpenAI-compatible LLM endpoint for enrichment (MacLustr llm-api.io).

# Quickstart

bash

uv venv --python 3.12 .venv && uv pip install --python .venv/bin/python -e '.[dev]'
createdb -O companyatlas companyatlas            # role companyatlas/companyatlas; extensions pg_trgm + uuid-ossp
cp .env.example .env
.venv/bin/catlas migrate && .venv/bin/catlas seed   # schema + industries/countries/companies (Wikidata registry)
.venv/bin/catlas discover https://stripe.com --dry-run
.venv/bin/catlas onboard --limit 100             # discovery → sensors
.venv/bin/catlas schedule                         # crawl + intelligence loop
.venv/bin/catlas api                              # http://127.0.0.1:8371/api/v1/docs
pnpm install && pnpm dev:web                      # http://localhost:8370
.venv/bin/pytest -q && .venv/bin/ruff check src tests && pnpm -r typecheck

# Principles (short form)

Historical-first · raw and interpreted data kept separate · deterministic pipeline first, LLMs only as budgeted enrichment · reusable connector families, automatic discovery · polite and lawful crawling (robots, per-domain limits, SSRF guard, never bypass challenges, no private data) · provenance and confidence on every fact · careful language ("no longer listed", never "fired") · no magic numbers · mobile first-class · never fabricate.

Contact: contact@spboucher.ai · crawler identity CompanyAtlasBot (see /bot). Hosted on MacLustr.