SDD (Specification-Driven Development) is the workflow this course follows: starting from a PRD (Product Requirements Document), you produce a specification, then a technical plan, then decomposed tasks, and finally implementation.
A technical plan translates functional requirements into concrete technical decisions. It has 7 key sections.
Reference: CODEX.md
Throughout this lesson, several sections reference CODEX.md. This is a project-level conventions file that Codex reads to understand your codebase's patterns, structure, and standards. When generating a technical plan, Codex uses it to make decisions consistent with your existing project.
Here is the CODEX.md for the TaskMaster project used in all examples below:
Markdown
# TaskMaster CODEX.md## Project OverviewTaskMaster is a task management API built with Python 3.11, FastAPI,SQLAlchemy, and PostgreSQL.## ArchitectureAll features follow the layered architecture pattern: API Router → Service → Repository → Database## Patterns & Conventions### Repository Pattern- ALL database access must go through repository classes- Repositories live in src/repositories/- Never access the database directly from services or API handlers### Dependency Injection- Use FastAPI's Depends() for all dependencies- Standard dependencies: get_db (database session), get_current_user (auth)### Error Handling- Raise HTTPException with appropriate status codes- Services raise domain exceptions; API layer converts to HTTPException- Standard codes: 400 (validation), 401 (unauthenticated), 403 (forbidden), 404 (not found)### Type Hints- All functions must have full type hints- Use Pydantic schemas for all request/response serialization## Directory Structuresrc/ api/ # FastAPI routers models/ # SQLAlchemy models schemas/ # Pydantic schemas services/ # Business logic repositories/ # Database access database.py # Session managementtests/ unit/ # Unit tests with mocked dependencies integration/ # Integration tests with TestClient## Testing Standards- Repositories: 95%+ coverage- Services: 90%+ coverage- API endpoints: 85%+ coverage- All authorization logic must be tested
Every decision in your technical plan should be traceable back to these conventions.
Join the 1M+ learners on CodeSignal
Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal
1. Architecture (Component Interactions)
## Architecture: Task CommentsComponent Flow:Client → API Endpoint → CommentService → CommentRepository → DatabaseData Flow:1. Client sends POST /api/tasks/{id}/comments with JWT2. API validates token, calls `CommentService.create_comment()`3. Service validates: user owns task, content length valid4. Service calls CommentRepository.create()5. Repository persists via SQLAlchemy, returns Comment6. API transforms to CommentSchema, returns 201
Why: Prevents conflicting assumptions about layer responsibilities, duplicate validation, and architectural drift.
How to decide: Start from entry point → follow data transformations → identify decision points → validate against CODEX.md.
2. Data Model (Database Schema)
## Data Model: CommentTable: comments- id: UUID, primary key, default=uuid4- task_id: UUID, FK to tasks.id, NOT NULL- user_id: UUID, FK to users.id, NOT NULL- content: String(5000), NOT NULL- created_at: DateTime, default=utcnow, NOT NULLRelationships:- task: relationship to Task (backref="comments")- author: relationship to User (backref="comments")Indexes:- (task_id, created_at) for chronological listing
Why: Prevents inadequate coverage, untested authorization, and missing edge cases.
Common mistakes: "Write some tests", no coverage targets, only unit OR integration, no error case testing.
How to decide: One test file per production file, repositories 95%+, services 90%+, APIs 85%+, test authorization and validation critically. (These targets come directly from CODEX.md's Testing Standards.)
7. Security Considerations
## SecurityAuthorization:- Verify user owns task before comment creation- DELETE: Allow comment owner OR task ownerInput Validation:- Content: 1-5000 characters- Use SQLAlchemy ORM (no raw SQL)Data Leaks:- Use Pydantic schemas for responses (never raw ORM)- Only return comments for user's tasks
Why: Prevents authorization bypasses, injection attacks, and data leaks.
Common mistakes: No authorization, missing validation, raw SQL, returning ORM objects directly.
How to decide: Check authorization in service layer, validate all inputs, use ORM, always use Pydantic schemas, exclude sensitive fields.
## Architecture: Task CommentsComponent Flow:Client → API Endpoint → CommentService → CommentRepository → DatabaseData Flow:1. Client sends POST /api/tasks/{id}/comments with JWT2. API validates token, calls `CommentService.create_comment()`3. Service validates: user owns task, content length valid4. Service calls CommentRepository.create()5. Repository persists via SQLAlchemy, returns Comment6. API transforms to CommentSchema, returns 201
Markdown
## Data Model: CommentTable: comments- id: UUID, primary key, default=uuid4- task_id: UUID, FK to tasks.id, NOT NULL- user_id: UUID, FK to users.id, NOT NULL- content: String(5000), NOT NULL- created_at: DateTime, default=utcnow, NOT NULLRelationships:- task: relationship to Task (backref="comments")- author: relationship to User (backref="comments")Indexes:- (task_id, created_at) for chronological listing
Markdown
## API ImplementationPOST /api/tasks/{task_id}/comments- Router: src/api/comments.py, async def create_comment()- Dependencies: current_user, comment_service- Response: 201 with CommentSchema- Errors: 400/401/403/404- Error handling: Catch service exceptions → HTTPExceptionGET /api/tasks/{task_id}/comments- Query params: skip (0), limit (50)- Response: 200 with List[CommentSchema]DELETE /api/comments/{comment_id}- Authorization: comment owner OR task owner- Response: 204 No Content
## SecurityAuthorization:- Verify user owns task before comment creation- DELETE: Allow comment owner OR task ownerInput Validation:- Content: 1-5000 characters- Use SQLAlchemy ORM (no raw SQL)Data Leaks:- Use Pydantic schemas for responses (never raw ORM)- Only return comments for user's tasks
Markdown
Given approved specification (specs/task-comments/specification.md),generate technical plan for TaskMaster.Context: Review CODEX.md, analyze existing codeStack: Python 3.11, FastAPI, SQLAlchemy, PostgreSQLRequired: Architecture, Data Model, API, Module Structure, Integration Points, Testing, SecurityConstraints: Repository pattern, DI, type hints, HTTPException
