ARCHITECTURE.md

Backend Architecture - Domain-Driven Design

Last Updated: 2026-01-15
Status: Production Ready ✅

---

🏛️ Architecture Overview

The backend follows a clean domain-driven architecture with clear separation between infrastructure and business logic.

Layer Structure

Backend
├── core/                    # Shared kernel (models, database, config)
├── app/
│   ├── modules/            # Domain Services (Business Logic)
│   │   ├── auth/          # Authentication & authorization
│   │   ├── cases/         # Case management
│   │   ├── users/         # User management
│   │   ├── analytics/     # Analytics & reporting
│   │   ├── transactions/  # Transaction management
│   │   └── evidence/      # Evidence handling
│   ├── services/
│   │   ├── infrastructure/   # Infrastructure services
│   │   │   ├── auth_service.py       # JWT & auth (shim)
│   │   │   ├── cache_service.py      # Multi-layer caching
│   │   │   ├── logging_service.py    # Structured logging (shim)
│   │   │   ├── rbac_service.py       # Role-based access
│   │   │   └── storage/
│   │   │       └── database_service.py  # DB infrastructure ONLY
│   │   └── ai/              # AI & ML services
│   └── routers/            # API endpoints
└── tests/                  # Test suites

---

🎯 Core Principles

1. Domain-Driven Design

• Domain Services (app/modules/*) contain ALL business logic
• Infrastructure Services (app/services/infrastructure/*) provide technical capabilities
• Clear boundaries between domains

2. Single Responsibility

• Each service has ONE clear purpose
• No overlapping functionalities
• Business logic separated from infrastructure

3. Dependency Direction

Routers → Domain Services → Repositories → Database
          ↓
     Infrastructure Services (cache, logging, etc.)

---

📦 Domain Services

Authentication (app/modules/auth/)

Purpose: User authentication, JWT tokens, MFA
Key Methods:

• register_user()
• authenticate_user()
• verify_token()
• enable_mfa()

Router: app/modules/auth/router.py

---

Case Management (app/modules/cases/)

Purpose: Fraud case lifecycle management
Key Methods:

• get_cases_paginated() - List cases with filters
• create_case() - Create new investigation
• update_case() - Modify case details
• get_case_stats() - Case statistics
• add_note() - Add case notes
• delete_case() - Remove case

Router: app/modules/cases/router.py
Repository: CaseRepository (data access)
Service: CaseService (business logic)

---

User Management (app/modules/users/)

Purpose: User administration and preferences
Key Methods:

• get_users_paginated() - List users
• create_user() - Register new user
• update_user() - Modify user data
• update_preferences() - User settings
• delete_user() - Remove user

Router: app/modules/users/router.py

---

Analytics (app/modules/analytics/)

Purpose: Business intelligence and reporting
Key Methods:

• get_case_analytics() - Case metrics over time
• get_transaction_aggregates() - Transaction stats
• get_dashboard_data() - Dashboard metrics
• generate_risk_heatmaps() - Risk visualization

Router: app/modules/analytics/router.py

---

Transactions (app/modules/transactions/) ⭐ NEW

Purpose: Financial transaction management
Key Methods:

• get_transactions_by_case() - List transactions
• create_transaction() - Add new transaction
• update_transaction_status() - Change status
• get_transaction_aggregates() - Calculate totals

Router: TBD (can be added if needed)

---

Evidence (app/modules/evidence/)

Purpose: Digital evidence handling
Key Methods:

• get_evidence_paginated() - List evidence
• process_file() - Process uploaded files
• delete_evidence() - Remove evidence

Router: app/modules/evidence/router.py

---

🔧 Infrastructure Services

Database Service (infrastructure/storage/database_service.py)

Purpose: INFRASTRUCTURE ONLY ⚠️

What it DOES:

• ✅ Session management (get_db())
• ✅ Connection pooling
• ✅ Health checks (health_check())
• ✅ Performance monitoring
• ✅ Query caching utilities

What it DOES NOT do:

• ❌ Business logic (moved to domain services)
• ❌ Case/user/transaction queries (use domain services)
• ❌ Data aggregations (use AnalyticsService)

Migration: All business methods → Domain services

---

Cache Service (infrastructure/cache_service.py)

Purpose: Multi-layer caching (memory + Redis)
Features:

• L1: Fast in-memory cache
• L2: Larger in-memory cache
• L3: Redis distributed cache
• Automatic namespace management
• Cache statistics

---

Logging Service (infrastructure/logging_service.py)

Purpose: Structured logging with PII scrubbing
Features:

• JSON formatted logs
• Automatic PII detection & masking
• Email, SSN, credit card scrubbing
• Context enrichment

---

RBAC Service (infrastructure/rbac_service.py)

Purpose: Role-based access control
Features:

• Role hierarchy
• Permission checking
• FastAPI dependencies for auth

---

🔄 Data Flow

Typical Request Flow

1. HTTP Request
   ↓
2. Router (FastAPI endpoint)
   ↓
3. Authentication (auth_service.get_current_user)
   ↓
4. Authorization (rbac_service.require_role)
   ↓
5. Domain Service (business logic)
   ↓
6. Repository (data access)
   ↓
7. Database (via db_service.get_db)
   ↓
8. Response

Example: Get Cases

# router.py
@router.get("/cases")
async def list_cases(
    db: Session = Depends(get_db),
    current_user: User = Depends(auth_service.get_current_user),
):
    # Use domain service
    from app.modules.cases.service import case_service
    
    result = case_service.get_cases_paginated(
        db, page=1, per_page=20, filters={}
    )
    return result

---

📐 Design Patterns

Repository Pattern

Location: app/modules/*/repository.py

Purpose: Encapsulate data access logic
Responsibilities:

• SQL queries
• ORM operations
• Data mapping

Example:

class CaseRepository:
    def get_paginated(self, page, per_page, filters):
        query = self.db.query(Case)
        # Apply filters, pagination
        return query.all(), query.count()

Service Pattern

Location: app/modules/*/service.py

Purpose: Business logic orchestration
Responsibilities:

• Business rules
• Validation
• Transaction management
• Calling repositories

Example:

class CaseService:
    def create_case(self, db, data, creator_id):
        repo = CaseRepository(db)
        case = repo.create(data)
        db.commit()
        return case

Dependency Injection

Framework: FastAPI's Depends()

Common Dependencies:

• get_db() - Database session
• auth_service.get_current_user() - Current authenticated user
• rbac_service.require_admin() - Role requirements

---

🚀 Migration Guide

From database_service to Domain Services

❌ OLD WAY (Don't use)

from app.services.infrastructure.storage.database_service import db_service

# WRONG - business logic in infrastructure
cases = db_service.get_cases_paginated(page=1, per_page=20)

✅ NEW WAY (Correct)

from app.modules.cases.service import case_service
from core.database import get_db

# CORRECT - business logic in domain service
db = next(get_db())
cases = case_service.get_cases_paginated(db, page=1, per_page=20, filters={})

Quick Reference

Old (database_service)	New (Domain Service)
db_service.get_cases()	case_service.get_cases_paginated()
db_service.get_case_stats()	case_service.get_case_stats()
db_service.get_users_paginated()	user_service.get_paginated()
db_service.get_case_analytics()	analytics_service.get_case_analytics()
db_service.get_transaction_aggregates()	analytics_service.get_transaction_aggregates()
db_service.get_transactions_by_case()	transaction_service.get_transactions_by_case()

---

✅ Benefits of This Architecture

1. Maintainability

• Clear separation of concerns
• Easy to find where logic lives
• Single responsibility per service

2. Testability

• Mock repositories easily
• Test business logic independently
• Infrastructure tests separate

3. Scalability

• Services can be extracted to microservices
• Clear boundaries for team ownership
• Easy to add new domains

4. Security

• Business logic protected by service layer
• Consistent authorization patterns
• PII scrubbing at infrastructure level

5. Performance

• Caching at the right layer
• Query optimization in repositories
• Infrastructure monitoring separate from business

---

📊 Code Metrics

Before Consolidation

• database_service.py: 1,086 lines (mixed business + infrastructure)
• Overlapping cache services: 2 implementations
• Overlapping logging: 2 implementations
• Unused services: 6 files (~2,500 lines)

After Consolidation

• database_service.py: ~270 lines (pure infrastructure)
• Cache service: 1 unified implementation
• Logging service: 1 unified implementation + PII scrubbing
• Domain services: Clear separation across 6 modules

Impact

• 75% reduction in database_service.py
• ~3,000 lines removed (dead code)
• Zero overlapping functions
• Clean architecture achieved

---

🎯 Next Steps

For New Features

1. Identify the domain (cases, users, transactions, etc.)
2. Add methods to the appropriate domain service
3. Create repository methods if needed
4. Add router endpoints
5. Write tests

For Existing Code

1. Check if using database_service for business logic
2. Migrate to appropriate domain service
3. Update imports
4. Test thoroughly

For Infrastructure

1. Use database_service ONLY for:
   • Session management
   • Health checks
   • Performance monitoring
2. Everything else → domain services

---

📚 Related Documentation

• Consolidation Report
• Test Validation Report
• Database Service Cleanup Plan
• API Documentation

---

Architecture Status: ✅ Production Ready
Last Audit: 2026-01-15
Compliance: Clean Architecture, DDD, SOLID Principles