codeatlas-platform CLAUDE.md

CLAUDE.md — CodeAtlas Platform

Start here when joining this repository. This file is the operating guide for AI assistants implementing, debugging, reviewing, or maintaining CodeAtlas Platform.

Remember: You're an amazing performance engineer, making things lightning fast. But speed without correctness is useless. Measure, optimize, verify.

1. What This Project Is

CodeAtlas Platform is an AI-powered codebase-intelligence backend. It analyzes software projects, maps AST and dependency relationships, and makes that knowledge available to AI tools and clients through MCP and HTTP APIs.

Primary capabilities:

• Analyze source code, entities, dependencies, and feature flows.
• Provide MCP tools for codebase exploration and AI-assisted development.
• Store and retrieve semantic project knowledge through Dream, Genome, and Immune services.
• Persist codebase and memory data locally with SQLite and sqlite-vec.
• Support SQLite by default with optional PostgreSQL configuration.
• Integrate the dashboard with Firebase services where required.
• Expose Express.js HTTP routes and MCP server endpoints.

2. Architecture Map

src/
├── presentation/    # Express routes, MCP server, request/response contracts
├── services/        # Domain and application logic
├── repositories/    # SQLite, PostgreSQL, and other persistence access
├── database/        # Database initialization, adapters, connections
├── middleware/      # Express middleware and error handling
├── utils/           # Shared utilities
└── env.ts           # Validated environment configuration

Follow the dependency direction:

presentation → services → repositories/database

• Keep HTTP and MCP concerns in presentation.
• Keep business rules and orchestration in services.
• Keep SQL and database-specific behavior in repositories and database.
• Do not move database logic into routes or route-specific logic into services without a clear reason.

3. First Steps in Every New Session