Skip to content

ADR-034: Apps Folder Reorganization for Monorepo Structure

Status: Accepted
Date: 2024-10-15
Deciders: Architecture Team
Related: ADR-010 (Monorepo Restructuring)

Context

The original project structure had a flat organization with mixed concerns: - Agent code mixed with API code - Tool servers (MCP servers) scattered across directories - Shared models duplicated in multiple places - No clear separation between deployable units - Difficult to understand what gets deployed where

This made it challenging to: - Deploy services independently - Understand service boundaries - Manage dependencies properly - Scale development across team - Containerize individual services

Decision

Reorganize the repository into a clear monorepo structure with distinct apps:

apps/
├── api/                          # FastAPI backend + agent orchestration
│   ├── loan_defenders/
│   │   ├── api/                  # FastAPI routes and app
│   │   ├── agents/               # Agent implementations
│   │   └── tools/                # Agent tools (not MCP servers)
│   ├── pyproject.toml
│   └── Dockerfile
│
├── ui/                           # React frontend
│   ├── src/
│   ├── package.json
│   └── Dockerfile
│
├── mcp_servers/                  # MCP tool servers (deployed separately)
│   ├── application_verification/
│   │   ├── server.py
│   │   ├── service.py
│   │   ├── pyproject.toml
│   │   └── Dockerfile
│   ├── document_processing/
│   └── financial_calculations/
│
└── shared/                       # Shared code and models
    └── loan_defenders_models/    # Pydantic models package
        ├── application.py
        ├── assessment.py
        └── decision.py

Key Principles

  1. One app = One deployable unit
  2. Each folder under apps/ is independently deployable
  3. Each has its own Dockerfile

  4. Each has its own pyproject.toml/package.json

  5. Clear service boundaries

  6. API handles HTTP and orchestration
  7. UI handles frontend
  8. MCP servers provide specialized tools

  9. Shared package for common models

  10. Independent scaling

  11. Deploy 1 API instance
  12. Deploy 1 UI instance
  13. Deploy 3 MCP server instances (one per server type)

  14. Scale each independently based on load

  15. Package-based sharing

  16. Shared code in apps/shared/loan_defenders_models
  17. Published as internal package
  18. Version controlled dependencies

Implementation

Phase 1: Create apps/ Structure (Completed)

  • Created apps/ directory
  • Moved API code to apps/api/
  • Moved UI code to apps/ui/
  • Created apps/shared/ for models

Phase 2: Extract MCP Servers (Completed)

  • Moved tool servers to apps/mcp_servers/
  • Created separate Dockerfiles for each server
  • Established service-to-service communication

Phase 3: Package Management (Completed)

  • Created loan_defenders_models shared package
  • Set up proper Python path handling
  • Configured dependency management with uv

Phase 4: Containerization (Completed)

  • Created Docker Compose configuration
  • Built 5 separate containers
  • Established container networking

Consequences

Positive

✅ Clear deployment model: Each app is independently deployable
✅ Service boundaries: Obvious what each component does
✅ Independent scaling: Scale API, UI, MCP servers separately
✅ Parallel development: Teams can work on different apps
✅ Container-ready: Each app has its own Dockerfile
✅ Azure-ready: Maps directly to Container Apps instances

Negative

⚠️ More complexity: More directories and configuration files
⚠️ Dependency management: Need to manage shared package properly
⚠️ Python path handling: Requires careful PYTHONPATH configuration

Mitigations

  • Comprehensive documentation in each app's README
  • Shared package published and versioned properly
  • Dev container configuration handles PYTHONPATH
  • Docker builds handle imports correctly

Deployment Mapping

Local Development

Terminal 1: MCP Application Verification (Port 8010)
Terminal 2: MCP Document Processing (Port 8011)
Terminal 3: MCP Financial Calculations (Port 8012)
Terminal 4: API Server (Port 8000)
Terminal 5: UI Dev Server (Port 5173)

Docker Compose

5 services in docker-compose.yml:
- mcp-application-verification
- mcp-document-processing
- mcp-financial-calculations
- api
- ui

Azure Container Apps

5 Container App instances:
- loan-defenders-mcp-app-verification
- loan-defenders-mcp-doc-processing
- loan-defenders-mcp-fin-calc
- loan-defenders-api
- loan-defenders-ui

Migration Path

For developers working with the old structure:

Old location → New location - loan_processing/api/ → apps/api/loan_defenders/api/ - loan_processing/agents/ → apps/api/loan_defenders/agents/ - loan_processing/tools/mcp_servers/ → apps/mcp_servers/ - ui/ → apps/ui/ - loan_processing/models/ → apps/shared/loan_defenders_models/

References

Status

Implemented: October 2024
Current State: All apps reorganized and deployed successfully
Next Steps: Continue refining shared package usage