Python Architecture

Priority: P0 (CRITICAL)

Rules

• Keep domain decisions independent from HTTP, DB, env, and queue clients.
• Define ports where callers need substitution; implement adapters at the edge.
• Compose runtime dependencies in startup or wiring modules.
• Treat contracts, policy, and normalization helpers as standalone modules.

Recipe

1. Place pure contracts and policy in domain/application modules.
2. Keep adapters thin: DB, HTTP, bot, MCP, subprocess, storage.
3. Push workflow orchestration into services that call contracts and ports.
4. Separate report formatting from fact gathering.
5. Add focused regression tests before moving boundary code.