# Phase 2 Clarifications - Architect's Responses

**Date**: 2024-11-20
**Status**: All 23 questions answered
**Developer Action**: Proceed with implementation

## Overview

The Architect has provided complete answers to all 8 categories (23 specific questions) raised by the Developer. This document provides a quick reference to the decisions made.

**Full Details**: See `/docs/designs/phase-2-implementation-guide.md` for complete implementation specifications.

**Architectural Decision Record**: See `/docs/decisions/0004-phase-2-implementation-decisions.md` for rationale and consequences.

## Quick Reference Answers

### 1. Rate Limiting Implementation

**Q: Should actual rate limiting be implemented or leave as stubs?**
- A: Implement actual rate limiting with in-memory storage

**Q: Should metadata storage use CodeStorage?**
- A: No, use simple dictionary in RateLimiter service instance

**Q: Should "Max 3 codes per domain per hour" be implemented?**
- A: Yes, with timestamp list tracking and automatic cleanup

### 2. Authorization Code Metadata Structure

**Q: Should storage include 'used' field in Phase 2?**
- A: Yes, include now (set to False, consume in Phase 3)

**Q: Use Phase 1's CodeStorage or separate storage?**
- A: Reuse Phase 1's CodeStorage with key prefix `authz:`

**Q: Store datetime objects or epoch integers?**
- A: Epoch integers (simpler)

### 3. HTML Template Implementation

**Q: Use Jinja2 or plain Python f-strings?**
- A: Use Jinja2 templates

**Q: Where should template files be located?**
- A: `src/gondulf/templates/`

**Q: Reusable layout templates or self-contained?**
- A: Reusable `base.html` with template inheritance

**Q: Template files vs inline HTML?**
- A: Separate template files

### 4. Database Migration Timing

**Q: Apply migration 002 as part of Phase 2?**
- A: Yes, apply immediately before Phase 2 implementation

**Q: Is migration necessary since Phase 1 doesn't write to domains?**
- A: Yes, keeps schema current with code expectations

**Q: Should new code use 'two_factor' immediately?**
- A: Yes, assume column exists (migration handles it)

### 5. Client Validation Helper Functions

**Q: Implement as standalone functions or methods on helper class?**
- A: Standalone functions in `src/gondulf/utils/validation.py`

**Q: Create shared utility module?**
- A: Yes, `gondulf.utils.validation` module

**Q: Full subdomain validation now or stub for Phase 3?**
- A: Full validation now (security should be complete)

### 6. Error Response Format Consistency

**Q: Should verification endpoints return JSON (200 OK with success:false)?**
- A: Yes, always JSON with 200 OK

**Q: Should authorization endpoint errors return HTML or redirects?**
- A: Depends on validation stage:
  - Pre-client validation: HTML error page
  - Post-client validation: OAuth redirect with error

**Q: When to use HTML vs OAuth redirect errors?**
- A: See decision tree in implementation guide

### 7. Dependency Injection Pattern

**Q: Create dependencies.py module?**
- A: Yes, `src/gondulf/dependencies.py`

**Q: Services instantiated at startup (singleton) or per-request?**
- A: Singleton at startup using `@lru_cache()`

**Q: Configuration passed at instantiation or read each time?**
- A: Read at instantiation (services configured once)

### 8. Test Organization for Authorization Endpoint

**Q: Separate test files per router?**
- A: Yes:
  - `test_verification_endpoints.py`
  - `test_authorization_endpoint.py`

**Q: Test sub-endpoints separately or as part of full flow?**
- A: Test complete flows (black box testing)

**Q: Shared fixtures for common scenarios?**
- A: Yes, use `tests/conftest.py` for shared fixtures

## Implementation Priority

All decisions are final and ready for implementation. The Developer should:

1. **Read** `/docs/designs/phase-2-implementation-guide.md` thoroughly
2. **Review** code examples and patterns provided
3. **Apply** migration 002 before starting implementation
4. **Implement** following the exact patterns specified
5. **Ask** additional questions ONLY if new ambiguities arise

## Architect's Guiding Principles

Every decision made reflects these core values:
- **Simplicity**: Real implementations using simple patterns
- **Reuse**: Leverage Phase 1 infrastructure where possible
- **Standards**: Use established tools (Jinja2, FastAPI patterns)
- **Clarity**: Explicit structures over implicit behavior
- **Security**: Complete security features, not stubs

## Status

**DESIGN READY: Phase 2 Implementation - All clarifications resolved**

Developer: Please proceed with implementation following the patterns in the implementation guide.