Clean Architecture Patterns
Relevant source files
The following files were used as context for generating this wiki page:
Thoth organizes its codebase using Clean Architecture principles to separate domain logic from infrastructure concerns. The project isolates business rules in the domain layer, orchestrates them in the application layer, and connects to external systems through the infrastructure and interface layers.
This architecture ensures that the core logic—such as user bio management and authentication—remains independent of specific frameworks like Express or the Model Context Protocol (MCP) SDK.
Layered Structure
The project separates concerns into specific directories within apps/ and packages/ to maintain the dependency rule, where dependencies point inward toward the core logic.
| Layer | Responsibility | Directory Example |
|---|---|---|
| Domain | Contains enterprise business rules and entities. | apps/api/src/modules/bio/domain/ |
| Application | Orchestrates domain entities to perform specific tasks. | apps/api/src/modules/bio/application/ |
| Interface | Handles delivery mechanisms (MCP Tools, HTTP Routers). | apps/api/src/modules/bio/interface/ |
| Infrastructure | Implements technical details (Database, Auth Servers). | apps/api/src/infrastructure/ |
Sources: CLAUDE.md:14-19, apps/api/test/modules/bio/interface/bio.tool.integration.test.ts:7-9
Domain Layer
Entities represent the core business data and constraints. For example, the Bio entity validates that fields like handle, name, and headline are not blank during construction.
Sources: apps/api/test/modules/bio/domain/bio.test.ts:14-23
Application Layer
Services in the application layer coordinate domain actions. The BioService provides methods like get, create, and update which are then utilized by interface-level tools.
Sources: apps/api/test/modules/bio/interface/bio.tool.integration.test.ts:32-37
Dependency Injection and Inversion
Thoth uses inversify to manage dependencies and decouple components. The AppRouter class injects specialized routers and ports, allowing the system to swap implementations without modifying the routing logic.
The diagram shows how AppRouter aggregates various specialized routers and the AuthPort through dependency injection.
Sources: apps/api/src/infrastructure/http/app-router.ts:25-39
Interface Patterns: MCP and HTTP
The project exposes functionality through dual interfaces: traditional HTTP endpoints and Model Context Protocol (MCP) tools. This allows both web clients and AI agents to interact with the same application services.
MCP Tool Registration
The BioTool registers specific functions to the MCP server. It maps internal service calls to JSON-RPC methods.
get_bio: Publicly accessible tool to retrieve bio data.create_bio: Private tool for owner bio creation.update_bio: Private tool for owner bio updates.
Sources: apps/api/test/modules/bio/interface/bio.tool.integration.test.ts:42-48, apps/api/spec/bio.md:10-12
Request Flow
The following sequence diagram illustrates how a request flows from an external client through the infrastructure and interface layers into the application service.
The flow shows the interception of requests by middleware before they reach the tool interface and application service.
Sources: apps/api/src/infrastructure/http/app-router.ts:58-66, apps/api/test/modules/bio/interface/bio.tool.integration.test.ts:74-81, apps/api/spec/auth.md:21-25
Security and Authentication Patterns
Security is handled at the infrastructure/middleware level. AuthPort provides a transport-neutral way to verify tokens, which is used by both HTTP routes and MCP tools.
Per-Call Authentication
While POST /mcp is a single endpoint, authentication is decided per-call based on the JSON-RPC body. Private tools return a 401 if called without a valid Principal.
Sources: apps/api/spec/auth.md:15-18, apps/api/test/infrastructure/http/server.integration.test.ts:192-205
Data Isolation
Every user-scoped row in the database carries a userId, and every query filters by this ID to ensure that users cannot access or modify each other's data (e.g., memory or bios).
Sources: apps/api/spec/auth.md:33-33, apps/api/spec/auth.md:65-68
Summary
Thoth implements Clean Architecture by strictly separating domain entities from technical infrastructure. By leveraging dependency injection and a modular routing system, it supports multiple interface types (HTTP and MCP) while maintaining consistent security and validation rules across the entire application.