The Modular Monolith and Clean Boundaries

A modular monolith deploys one application while preserving strong internal boundaries. It is the best default for SupportDesk AI because transactions, refactoring, testing, and operations remain simple. Domain and application code point inward; FastAPI, PostgreSQL, Redis, queues, and model providers remain replaceable outer adapters connected at one composition root.

What will you be able to do?

• split code by business capability and architectural responsibility;
• define ports for repositories and model gateways;
• keep routes thin and domain code framework-free;
• identify evidence that may justify service extraction later.

What should the project tree express?

Modules follow capabilities, then separate inward logic from adapters. A repository port uses application language:

The application service depends on these protocols. SQLAlchemy and a provider SDK implement them outside. main.py wires real implementations; tests wire fakes.

What belongs in a route?

A route parses trusted framework inputs, invokes one use case, maps the result, and chooses HTTP semantics. It does not build prompts, perform SQL, authorize by scattered if statements, or commit transactions.

When should a service be extracted?

Look for independent scaling needs, security isolation, fault isolation, release ownership, regulatory boundaries, or a stable capability used through a clear contract. “The folder is large” is not sufficient. Extraction replaces local calls with networks, partial failures, duplicated data, and distributed operations.

Why does this matter in AI-native systems?

AI libraries churn quickly. A model gateway port protects domain and application logic from provider response types. Prompt templates and output schemas may live with the AI feature, while execution adapters own provider-specific serialization, retries, and telemetry.

Common mistakes

• “Clean architecture” creates dozens of pass-through classes with no boundary value.
• Shared common modules let capabilities mutate one another's tables.
• Routes become the only place business rules exist.
• Tests mock internal methods instead of using stable ports.
• Microservices are introduced before observability and reliable delivery exist.

AI Pair-Programmer Prompt

Exercise

Move ticket creation into an application service using a repository protocol and unit of work. Provide an in-memory fake and SQL adapter.

Acceptance criteria: the same use-case tests pass against the fake and an integration database; application modules import no FastAPI, SQLAlchemy, Redis, or model SDK.

Knowledge check

1. What makes a modular monolith different from unstructured monolithic code?
2. Where are concrete adapters assembled?
3. Name one valid reason to extract a service.

---

Answers

1. Enforced capability and dependency boundaries inside one deployment.
2. The composition root.
3. Independent scale, security/fault isolation, ownership, regulation, or a stable remote capability boundary.

Completion checklist

• Dependency direction points inward.
• Routes are transport adapters.
• Every abstraction earns testing or substitution value.

Primary references

• Python Protocols
• Domain-Driven Design reference