Gondulf/docs/CLARIFICATIONS-ANSWERED.md

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.