Connapse CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Run

# Build
dotnet build

# Run web app (requires backing services)
dotnet run --project src/Connapse.Web

# Start backing services (PostgreSQL + MinIO, ports exposed to host)
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d

# Full stack via Docker
docker compose up -d

Tests

# All tests
dotnet test

# Unit tests only (no Docker required)
dotnet test --filter "Category=Unit"

# Integration tests (needs Docker for Testcontainers)
dotnet test --filter "Category=Integration"

# Single test class
dotnet test --filter "FullyQualifiedName~Connapse.Core.Tests.CloudScope.CloudScopeServiceTests"

# Single test method
dotnet test --filter "FullyQualifiedName~ClassName.MethodName_Scenario_ExpectedResult"

• xUnit framework, FluentAssertions (.Should()), NSubstitute for mocking
• Integration tests share a single PostgreSQL+MinIO container pair via SharedWebAppFixture (collection-based)
• Tag tests: [Trait("Category", "Unit")] or [Trait("Category", "Integration")]
• Test naming: MethodName_Scenario_ExpectedResult

Database Migrations

Two separate EF Core migration histories:

• KnowledgeDbContext (Storage): dotnet ef migrations add Name --project src/Connapse.Storage
• ConnapseIdentityDbContext (Identity): dotnet ef migrations add Name --project src/Connapse.Identity

Migrations run automatically on app startup.

Architecture

Connapse.Web          (Blazor Server + Minimal API endpoints + MCP server)
├── Connapse.Identity (Auth: OAuth 2.1/JWT/PAT/cookie, cloud identity, audit)
├── Connapse.Ingestion(Parsers, chunking strategies, background worker)
├── Connapse.Search   (Vector, keyword, hybrid search + reranking)
├── Connapse.Storage  (PostgreSQL/pgvector, EF Core, connectors, embedding/LLM providers)
├── Connapse.Agents   (Agent orchestration)
└── Connapse.Core     (Domain models, interfaces, settings records — zero dependencies)