Aperture

Analyst-grade OSINT fusion platform. Cyber, maritime, aviation, and open-web intelligence on a single geospatial map, with a cross-domain Case File that exports to PDF and STIX 2.1.

Status: Phase 0 — repo scaffold. See CLAUDE.md for the full architecture decisions, source inventory, and phase plan.

---

Quickstart

The platform is designed to boot end-to-end with no API keys — every source adapter ships a mock implementation. Add real keys later to flip individual sources to live mode.

# 1. Clone and configure
git clone <repo> aperture && cd aperture
cp .env.example .env
# JWT_SECRET will be auto-generated by scripts/setup.sh if left blank.

# 2. Bring up infrastructure (Postgres + Redis)
docker compose up -d db redis

# 3. (Phase 2+) backend + worker + frontend
#    docker compose up -d backend worker frontend
#    open http://localhost:3000

Repository Layout

backend/    FastAPI app, adapters, Alembic migrations, Celery workers
frontend/   Next.js 14 App Router, MapLibre + Deck.gl + Kepler.gl
data/seed/  Downloaded seed datasets (gitignored)
deploy/k8s/ Kubernetes manifest stubs (not used in v1)
scripts/    One-off helpers (setup, seed, key generation)
docs/       Long-form docs (analyst guide lands here in Phase 8)

Deploying

Local development uses docker compose. For a cloud deploy (Vercel frontend + Fly.io backend + Timescale Cloud + Upstash Redis), see DEPLOY.md.

Tooling

• Backend: Python 3.12 + uv + FastAPI + Celery + SQLAlchemy + Alembic. Lint with ruff + black.
• Frontend: Node 20 + pnpm + Next.js 14 + TypeScript + Tailwind + shadcn/ui. Lint with eslint + prettier.
• Pre-commit: pre-commit install after cloning.

Contributing

Read CLAUDE.md first. The non-negotiables:

1. No fabricated API endpoints. Read the live docs for any source before writing the real adapter; ship a typed interface + mock if the auth/shape isn't clear.
2. Mock-first. A new adapter lands with its mock before its real implementation. The platform must keep booting with empty .env.
3. Secrets via env only. .env.example is the contract.
4. Lint and the relevant tests must pass at every phase boundary.

License

TBD (post-v1).