CodeAtlas Platform

Name: codeatlas-platform
Author: giauphan

AI-powered codebase intelligence platform — MCP Server, AST analysis, Knowledge Graph, and semantic memory with SQLite + sqlite-vec as the default database.

Ship a secure, multi-tenant codebase intelligence backend without rebuilding authentication, MCP tooling, semantic memory, and knowledge graph infrastructure from scratch. CodeAtlas Platform is an open-source foundation for developers who want a clear starting point for AI-native code analysis services.

[!IMPORTANT]
This repository is a foundation, not a substitute for a threat model. Review Known limitations and adapt the defaults to your infrastructure before serving production traffic.

Why this platform?

Concern	Included foundation
MCP Server	30+ tools via stdio or SSE transport (Claude, Cursor, VSCode)
Semantic memory	Dream memory store with SQLite + sqlite-vec vector search
Knowledge graph	Genome DNA + immune system patterns, consolidation engine
Multi-tenant	Tenant isolation via `authStorage.run` + Firebase auth
AST analysis	TypeScript/Python/JS parsing via `@typescript-eslint/typescript-estree` and `py-ast`
Security scanner	Enterprise vulnerability scanning built-in
A2A protocol	Agent-to-agent orchestration with registry
Dashboard	React + Vite management UI for API keys and projects

Architecture

AI IDE (Claude/Cursor) → MCP (stdio/SSE) → Platform :3381 → SQLite + sqlite-vec + Firebase + NVIDIA

Layer	Components
Presentation	Express HTTP, MCP SSE, A2A Agent Protocol, REST API
Services	Dream Memory, Genome DNA, Second Brain, Consolidation Engine, Security Scanner
Data	SQLite + `sqlite-vec` (PostgreSQL optional), Firebase Firestore, NVIDIA NIM embeddings

Architecture diagrams

Diagram	File
System architecture	`diagrams/system.mmd`
Second Brain flow	`diagrams/second-brain.mmd`
Dream lifecycle	`diagrams/dreams.mmd`
Genome + Immune system	`diagrams/genome.mmd`
MCP architecture	`architecture/mcp.md`
Deployment	`diagrams/deployment.mmd`
A2A + Sync	`diagrams/a2a-sync.mmd`

Quick start

Requirements

Node.js 20+
pnpm 9+ (corepack enable && corepack prepare pnpm@9 --activate)
SQLite + sqlite-vec (bundled — no external database server required)
Firebase service account (for multi-tenant auth)
NVIDIA NIM API key (for embeddings)

1. Clone and install

git clone https://github.com/giauphan/codeatlas-platform.git
cd codeatlas-platform
pnpm install

2. Configure environment

cp .env.example .env
# Edit .env with your Firebase and NVIDIA credentials

See docs/CONFIGURATION.md or docs/DEVELOPMENT.md for the full env var reference.

3. Build

pnpm run build

4. Initialize database

pnpm run db-init

5. Start the server

# Production mode (SSE on :3381)
PORT=3381 pnpm start

# Development mode (hot reload)
pnpm run dev

# Stdio mode (for Claude Desktop — leave PORT unset)
pnpm start

Server runs at http://localhost:3381. Health check: GET /health.

MCP integration

Claude Desktop (stdio)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "codeatlas": {
      "command": "npx",
      "args": ["-y", "codeatlas-ai"],
      "env": {
        "CODEATLAS_API_KEY": "your_api_key"
      }
    }
  }
}

Cursor / VSCode (SSE)

{
  "mcpServers": {
    "codeatlas": {
      "url": "http://localhost:3381/sse"
    }
  }
}

See docs/API_EXAMPLES.md for full curl flows and transport modes.

MCP tools (30+)

Category	Tools
Dreams	`save_dream_memory`, `query_dream_memories`, `sync_dreams`
Genome	`search_genome`, `save_genome`, `scan_immune`
Skills	`search_skills`, `get_skill`, `install_skill`
Scanner	`scan_enterprise_vulnerabilities`
Code	`code_search`, `search_files`, `read_file`
Projects	`list_projects`, `get_project_structure`, `get_dependencies`
Architecture	`generate_system_flow`, `generate_feature_flow_diagram`, `trace_feature_flow`

Full tool reference: docs/architecture/mcp.md.

Documentation

Guide	Purpose
Development	Local dev setup, env vars, troubleshooting
Deployment	PM2, systemd, Nginx TLS reverse proxy
API examples	curl flows, MCP configs, REST endpoints
Architecture overview	Layers, services, integrations
MCP architecture	Tool registration, transports, request flow
Quick setup	Legacy condensed guide

Known limitations

SQLite dependency: Data lives in a local SQLite file (default ./data/codeatlas.db) with sqlite-vec for vector search. Postgres is available as an opt-in backend.
Firebase auth: Multi-tenant mode requires Firebase Admin SDK + service account. API-key-only mode supported for single-tenant.
NVIDIA embeddings: Vector search depends on NVIDIA NIM API. Without NVIDIA_API_KEY, queries fall back to date-ordered results.
Local indexing: Pure cloud deployments cannot index local code — run the codeatlas-ai client locally to sync AST data.
Dashboard: Management UI ships separately in dashboard/ — build and deploy independently.

See CHANGELOG.md for release history.

Contributing

Bug reports, documentation fixes, tests, and focused feature contributions are welcome. Start with CONTRIBUTING.md, then look for issues labeled good first issue or help wanted.

For security vulnerabilities, follow SECURITY.md instead of opening a public issue.

License

Distributed under the MIT License. Maintained by @giauphan.