CLAUDE.md#

This file provides guidance to coding agents when working with code in this repository.

Build & Development Commands#

# Install dependencies
poetry install

# Run unit tests
make test-unit
# Or directly:
poetry run pytest tests/

# Run a single test file
poetry run pytest tests/path_to_my_test_file.py

# Run tests with print output
poetry run pytest -s tests/

# Run tests in watch mode
poetry run ptw . -v tests/path/to/test.py

# Run integration tests (requires Docker)
make test-integration
# Or if services are running locally:
poetry run pytest tests/integration

# Linting (runs pre-commit on changed files)
make lint

# Manual formatting/linting
poetry run ruff check .
poetry run black .

# Type checking
poetry run mypy <module>

# Update snapshot tests
make test-update-snapshots

Docker Development#

# Build and start all services
make all-up

# Lightweight agent development (less resource-intensive)
make agent-up

# Interactive shell in dev container
make ipython # or: make bash

# Start specific services
make public-api-up
make search-up

Architecture Overview#

This is a Python backend monolith for Dosu, an AI assistant that monitors GitHub, Slack, Linear, and other platforms to help with knowledge management and thread intelligence.

Core Directories#

Application Entry Points#

• Internal API: api/main.py - Main FastAPI app for event handling
• Public API: public_api/main.py - Public-facing REST endpoints
• Internal API: internal/main.py - DBOS workflows and internal endpoints
• Search: search/main.py - Standalone search service

Key Patterns#

Event Flow: External webhook -> CloudFunction -> DBOS Queue -> Pub/Sub -> Agent Router -> Workflow -> Publish response

Workflow Composition: Workflows use pipe operator composition:

PreliminaryChecks() | Ack() | OrchestrateWorkflow()

Database: Supabase PostgreSQL with Row-Level Security (RLS). Use Engine.begin_as_user() for user-scoped queries.

Vector Search: LanceDB for semantic search over documents.

Module Dependencies: Enforced via tach.toml. Key allowed dependencies:

• agent depends on core, workflows
• workflows depends on core, api, search, data_syncing
• public_api depends on core, agent, workflows, data_syncing

Test Organization#

• tests/ - Unit tests (run by default with pytest)
• tests/integration/ - Integration tests (excluded by default, run explicitly)
• tests/e2e/ - End-to-end tests (excluded by default)

Integration and E2E tests require explicit paths: poetry run pytest tests/integration

Configuration#

Environment files loaded in order: .env -> .env.development -> .env.development.local

Key config in core/config.py and core/base_config.py.