Atlas
A free, open-source directory helping people discover who's working on the issues that matter most — in every community across America.
What is Atlas?
Across the country, thousands of organizations and individuals are working on housing, labor, climate, democracy, justice, and more. But finding them isn't easy. Information is scattered, outdated, or buried in search results.
Atlas changes that. It's a searchable, public directory powered by an AI-driven discovery engine that continuously finds and organizes information about the people and groups doing meaningful work in communities everywhere. Every entry is traced back to public sources, so you can see exactly where the information comes from.
This is a nonprofit, open-source project. To learn more about our mission and goals, see the Product Vision.
Getting Started
Whether you're a developer, researcher, organizer, or just curious — welcome. Here's how to get involved:
- Explore the project — Read the Product Vision to understand what we're building and why
- Set up a development environment — Follow the Getting Started guide
- Contribute — Check the Development Workflow for how we work together
For Developers
Quick Start
Prerequisites: Python 3.12+, Node.js 24+, and Make. See full prerequisites.
cd atlas
make setup
pnpm dev
| Service | URL |
|---|---|
| Frontend | http://app.localhost:1355 |
| API | http://api.localhost:1355 |
| API Docs | http://api.localhost:1355/docs |
[!TIP] We use Portless to manage local services. It eliminates port conflicts by providing stable, named URLs for each service. Ensure your local environment variables (e.g., in
app/.env.local) are updated to point to these URLs.
Documentation
Contributor documentation still lives in docs/, and the new Mintlify docs project lives in mintlify/:
| Section | Description |
|---|---|
| Getting Started | Installation, setup, and project orientation |
| Architecture | System design, data model, and pipeline |
| Development | Workflow, building features, and testing |
| Standards | Code style, commit conventions, and API design |
| Deployment | Production deployment and release process |
| Design | Product vision and system design documents |
For the Mintlify API docs:
- Config:
mintlify/docs.json - API pages:
mintlify/api-reference/ - Local validation:
pnpm docs:validate
Tech Stack
- Backend: Python 3.12, FastAPI, SQLite (FTS5)
- Frontend: TanStack Start (React + TypeScript)
- AI: Anthropic Claude API for structured data extraction
- DevOps: Docker Compose, Makefile, Turborepo
Connecting an MCP client
Atlas exposes a Model Context Protocol server at https://atlas.rebuildingus.org/mcp so AI assistants can search the catalog and pull place-level civic data through natural language. The server implements the 2025-11-25 MCP authorization spec end-to-end (RFC 8414 AS metadata, RFC 9728 protected-resource metadata, RFC 8707 resource indicators, PKCE S256, Client ID Metadata Documents) and is published to the MCP Registry as org.rebuildingus.atlas/atlas.
Setup walkthroughs, troubleshooting, and the full tool reference live in the Mintlify docs:
- MCP overview — what's available, what you need, which client guide to use.
- Client ID Metadata Documents — how a new client onboards without prior registration.
- Troubleshooting — decoding 401s, 403s, and silent failures.
- Authentication reference — token lifecycle, discovery URLs, scope catalog.
Contributing
Start with the Getting Started guide, then follow the Development Workflow for day-to-day practices. All commits must follow the Conventional Commits format, enforced automatically by git hooks.
License
This project is licensed under the MIT License.