Atlas

Single-tenant SaaS "company brain" for customer support. Ingests Zendesk tickets, Slack threads, and Notion docs; performs hybrid retrieval (vector + BM25) with cross-encoder rerank; synthesizes answers with Claude and inline citations. Surfaces are a Plasmo browser extension, a Slack bot, and a Next.js dashboard.

60-second quickstart

# 1. Install toolchain
brew install pnpm uv
pnpm install
uv sync --directory apps/api
uv sync --directory apps/reranker

# 2. Start local infra (Postgres + Redis + Inngest dev server)
./scripts/dev.sh up

# 3. Apply migrations
uv run --directory apps/api alembic upgrade head

# 4. Run services
uv run --directory apps/api uvicorn atlas.main:app --reload    # API on :8000
pnpm --filter @atlas/dashboard dev                              # Dashboard on :3000
pnpm --filter @atlas/extension dev                              # Plasmo dev build
uv run --directory apps/reranker uvicorn server:app --port 8081 # Reranker sidecar

Copy .env.example to .env and fill in the secrets before running. The local stack works without any cloud accounts for the API service itself; integration tests and LLM calls require real keys.

Repository layout

apps/api          FastAPI service (Python 3.12, uv)
apps/reranker     bge-reranker-v2 sidecar (Python, uv)
apps/dashboard    Next.js 14 App Router (TypeScript, pnpm)
apps/extension    Plasmo Manifest V3 extension (TypeScript, pnpm)
packages/sdk      Shared TS types + OpenAPI-generated client
evals             Benchmark + scoring harness
infra             Railway/Vercel configs (Terraform stubs)
docs              ADRs, runbooks, API contract, onboarding
scripts           Dev orchestration, seed, bench

Where to read next

• docs/onboarding.md — go from git clone to a green local server in under 30 minutes.
• docs/architecture/ — ADRs explaining every load-bearing decision.
• docs/runbooks/ — operational tasks (restore, secret rotation, incident response).
• docs/api/openapi.yaml — authoritative API contract.
• docs/contributing.md — coding standards, PR process, review expectations.

Engineering hard rules

Read the Ten Commandments before writing code. Highlights:

1. Tenant isolation is not optional. RLS is forced on every tenant-scoped table.
2. Every webhook handler and Inngest function is idempotent.
3. Every external call has timeout + retry + circuit breaker.
4. All LLM calls flow through apps/api/atlas/llm/.
5. Citations are sacred — refuse rather than hallucinate.

License

Proprietary — © Atlas, Inc.