Standardize Phase 1 Catalog Service File Structures

Summary

The Phase 1 catalog services have inconsistent file structures that create confusion and make pattern-matching difficult. We need to standardize them using an additive approach where all services share the same base structure, differing only by addition of domain-specific files.

Current State Analysis

Pattern A: Standard Catalog Pattern (Target)

Used by: calendar, scholarship, program, school, event, managing-org

app/
├── __init__.py
├── cache.py
├── crud.py
├── database.py
├── main.py
├── models.py
├── schemas.py
├── settings.py
├── middleware/
│   ├── __init__.py
│   └── auth.py
└── routers/
    ├── __init__.py
    ├── health.py
    └── {entity}.py

Pattern B: Phase 0 Pattern (Drift)

Used by: taxonomy, community-engagement, content

app/
├── __init__.py
├── main.py
├── models.py
├── schemas.py
├── auth.py              # ← at root, not middleware/
├── api/
│   └── routes/          # ← instead of routers/
│       ├── __init__.py
│       └── {entity}.py
├── core/
│   └── settings.py      # ← instead of settings.py at root
└── db/
    ├── base.py
    └── session.py       # ← instead of database.py at root

Inconsistencies Found

| Issue | Services Affected | Impact |
|-------|-------------------|--------|
| api/routes/ vs routers/ | taxonomy, community-engagement, content | Import path confusion |
| core/settings.py vs settings.py | community-engagement, content | Settings import inconsistency |
| db/session.py vs database.py | community-engagement, content | DB session import inconsistency |
| auth.py at root vs middleware/auth.py | scholarship, taxonomy, content | Auth import inconsistency |
| Missing middleware/ dir | scholarship, taxonomy, managing-org, event | No standard auth location |
| Missing cache.py | community-engagement | Caching pattern missing |

Target Standard Structure

All catalog services should follow this base structure:

{service}/
├── app/
│   ├── __init__.py
│   ├── cache.py                    # Redis caching utilities
│   ├── crud.py                     # Database operations + outbox emission
│   ├── database.py                 # DB session management
│   ├── main.py                     # FastAPI app + OutboxPublisher wiring
│   ├── models.py                   # SQLAlchemy models (or models/ for complex)
│   ├── schemas.py                  # Pydantic schemas (or schemas/ for complex)
│   ├── settings.py                 # Service configuration
│   ├── middleware/
│   │   ├── __init__.py
│   │   └── auth.py                 # JWT authentication
│   └── routers/
│       ├── __init__.py
│       ├── health.py               # Health check endpoint
│       └── {entities}.py           # Domain-specific routes
├── migrations/
│   ├── env.py
│   └── versions/
└── tests/

Allowed Additions (domain-specific)

Services may ADD these directories/files as needed:

• services/ - Complex business logic (managing-org, content)
• ingestion/ - Data import logic (competition)
• models/ directory - When models are complex (competition, content)
• schemas/ directory - When schemas are complex (competition, content)
• observability/ - Metrics/tracing (content)
• utils/ - Helper utilities

Implementation Plan

Phase 1: Taxonomy Service (smallest change)

• [ ] Move api/routes/ → routers/
• [ ] Move auth.py → middleware/auth.py
• [ ] Update imports in main.py

Phase 2: Community Engagement Service

• [ ] Move api/routes/ → routers/
• [ ] Move core/settings.py → settings.py
• [ ] Move db/session.py → database.py, merge with db/base.py
• [ ] Add cache.py (stub or basic implementation)
• [ ] Update imports throughout

Phase 3: Content Service

• [ ] Move api/routes/ → routers/
• [ ] Move core/settings.py → settings.py
• [ ] Move db/session.py → database.py
• [ ] Move auth.py → middleware/auth.py
• [ ] Keep services/, models/, schemas/, observability/, utils/ as-is (domain additions)
• [ ] Update imports throughout

Phase 4: Scholarship Service (minor fix)

• [ ] Move auth.py → middleware/auth.py
• [ ] Create middleware/__init__.py
• [ ] Update imports

Phase 5: Managing-org & Event Service (add middleware)

• [ ] Create middleware/ directory with auth stub or symlink to shared
• [ ] Verify all other files follow standard

Acceptance Criteria

• [ ] All 10 services have identical base file structure
• [ ] All services use routers/ (not api/routes/)
• [ ] All services use settings.py at app root (not core/settings.py)
• [ ] All services use database.py at app root (not db/session.py)
• [ ] All services have middleware/auth.py
• [ ] All services have routers/health.py
• [ ] All services pass existing tests after restructure
• [ ] All services start successfully

Labels

• cleanup
• phase-1
• file-structure