# 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.