Sequence 1: Foundation Infrastructure¶

Implementation guide with patterns carried forward

Overview¶

Attribute	Value
Sequence	1 of 18
Stories	S1-001 through S1-008
Dependencies	None (first sequence)
Status	In Progress

Stories in This Sequence¶

Story	Title	Requirements	Status
S1-001	Aurora PostgreSQL Setup	INF-001, INF-003, ENC-001, ENC-003	Done
S1-002	S3 Document Storage Setup	INF-004, RET-001, RET-003, ENC-001	Done
S1-003	Service Centralization Framework	AUD-001, AUD-007	Done
S1-004	Aurora Service Implementation	WISP-001, AUD-003, SEC-005	Done
S1-005	S3 Service Implementation	DOC-006, ENC-001, RET-004, RET-005	Done
S1-006	API Framework Setup	SEC-001 to SEC-004, AUD-001	Done
S1-007	Audit Logging Service	AUD-001 to AUD-007	Done
S1-008	Configuration Management	ENV-001, ENV-004	Done

S1-003: Service Centralization Framework¶

Requirements Traced¶

Req ID	Requirement	How Addressed
AUD-001	Log user actions	All service calls logged via BaseService
AUD-007	Log AI interactions	BedrockService logs all prompts/responses

Acceptance Criteria¶

BaseService class with logging, health check interface
ServiceRegistry singleton provides access to all services
Configuration loaded from config.yaml
Secrets loaded from AWS Secrets Manager (future)
Health check aggregates all service statuses
All service calls logged for audit

Implementation Checklist¶

src/services/base_service.py created
src/services/init.py with ServiceRegistry
Error handling per PATTERNS.md Section 1
Logging per PATTERNS.md Section 2

S1-006: API Framework Setup¶

Requirements Traced¶

Req ID	Requirement	How Addressed
SEC-001	User authentication	JWT middleware
SEC-002	Role-based access	RBAC middleware
SEC-003	Session management	JWT with refresh tokens
SEC-004	Failed login tracking	Audit log + lockout (pending)
AUD-001	Log user actions	Request logging middleware

Acceptance Criteria¶

FastAPI application with OpenAPI docs
JWT authentication for staff
JWT authentication for clients (tiered verification claims)
Role-based access control middleware
Rate limiting implemented
Request/response logging for audit
CORS configured

Implementation Checklist¶

src/api/main.py - FastAPI app
src/api/middleware/auth.py - JWT validation (25 tests)
src/api/middleware/rbac.py - Role checking
src/api/middleware/rate_limiting.py
src/api/middleware/correlation.py - Per PATTERNS.md Section 2.2
src/api/middleware/error_handler.py - Per PATTERNS.md Section 3.1
src/api/middleware/request_logging.py - Per PATTERNS.md Section 3.2

Infrastructure Requirements (Apply to ALL Stories)¶

Error Handling (PATTERNS.md Section 1)¶

Must implement before feature work:

# src/utils/exceptions.py - Exception hierarchy
# src/api/middleware/error_handler.py - Convert exceptions to JSON

# Usage in all code:
from src.utils.exceptions import NotFoundError, ConflictError, DatabaseError

try:
    result = await operation()
except asyncpg.UniqueViolationError:
    raise ConflictError("Resource already exists", field="email")

Logging (PATTERNS.md Section 2)¶

Must implement before feature work:

# src/utils/logging.py - structlog setup
# src/api/middleware/correlation.py - Correlation ID

# Usage in all code:
import structlog
logger = structlog.get_logger()

log = logger.bind(resource_id=str(id))
log.info("operation_started")
try:
    result = await do_thing()
    log.info("operation_completed", count=len(result))
except Exception as e:
    log.error("operation_failed", error=str(e))
    raise

Database Error Mapping¶

PostgreSQL Error	Application Error	User Message
UniqueViolationError	ConflictError	"Resource already exists"
ForeignKeyViolationError	ValidationError	"Referenced resource not found"
CheckViolationError	ValidationError	"Value out of allowed range"
PostgresConnectionError	ServiceUnavailableError	"Service temporarily unavailable"

Files to Create/Update¶

New Files Required¶

File	Purpose	Pattern Reference	Status
src/utils/exceptions.py	Exception hierarchy	PATTERNS.md 1.1	Done
src/utils/logging.py	Logging setup	PATTERNS.md 2.1	Done
src/api/middleware/correlation.py	Correlation ID	PATTERNS.md 2.2	Done
src/api/middleware/error_handler.py	Error responses	PATTERNS.md 3.1	Done
src/api/middleware/request_logging.py	Request logging	PATTERNS.md 3.2	Done

Existing Files to Update¶

File	Update Required	Status
src/services/aurora_service.py	Add try/catch with error mapping	Done
src/services/base_service.py	Add logging	Done
src/repositories/base_repository.py	Add error handling, logging	Done
src/repositories/client_repository.py	Add error handling, logging	Done
src/api/routes/clients.py	Use custom exceptions, add logging	Done
src/api/main.py	Add middleware stack	Done

Verification Checklist¶

Before marking Sequence 1 complete:

All database operations wrapped in try/catch
Errors logged with context (operation, parameters, error type)
Custom exceptions used throughout (not raw HTTPException)
Correlation ID flows through all logs
No PII in log messages
Unit tests for exception handling (123 tests passing)
Health check endpoint returns all service statuses