Overview

This assignment has three parts:

1. Domain modeling + schema design - draw and explain your proposed backend data model
2. Implement Module CRUD endpoints - implement and test contract-level behavior for the Module resource
3. Peer review + individual reflection - review a teammate’s PR and reflect on design + implementation

This assignment builds on HW1’s contract-level testing approach and introduces domain modeling and relationship design.

Suggestions for Division of Labor

Feel free to divide up the work as you see fit. That said, here’s a proposed division of labor:

1. Person 1: Models & Database
   • Create/update SQLAlchemy models (backend/models/module.py)
   • Handle relationships (many-to-many for courses, ordering for posts)
   • Database migrations if needed
2. Person 2: Schemas
   • Create Pydantic schemas (backend/schemas/module.py)
   • Request/response models
   • Validation logic
3. Person 3: Routes & Business Logic
   • Implement all 5 endpoints (backend/routes/modules.py)
   • Authentication/authorization checks
   • Error handling
4. Person 4: Tests
   • Write contract-level tests (tests/test_modules.py)
   • Success cases + failure cases for each endpoint
   • Ensure good test coverage
5. Person 5: Contracts & Integration (If Applicable)
   • Create GitHub issues with behavior contracts (section 2.2) for all endpoints
   • Coordinate integration between layers
   • Help with testing edge cases
   • Document API behavior

Coordination Tips

1. Start with contracts: Before coding, all agree on behavior contracts (section 2.2). This prevents mismatches.

2. Establish interfaces early:

   • Models person defines the model structure first
   • Schemas person can start once models are defined
   • Routes person can start once schemas are defined
   • Tests person can start once first endpoint is done

3. Use feature branches:

   • feature/models-module
   • feature/schemas-module
   • feature/routes-module
   • feature/tests-module

4. Integration checkpoints:

   • After models: Does the schema work with the model?
   • After schemas: Do the routes work with the schemas?
   • After routes: Do the tests pass?
   • Final: Does everything work together?

5. Review early and often:

   • Review models PR before schemas person starts
   • Review schemas PR before routes person starts
   • Review routes PRs as they’re created
   • Review tests PR before final integration

Timeline Suggestion

• Day 1: Design session + diagram creation
• Day 2: Models + Schemas (can work in parallel once models are done)
• Day 3: Routes implementation
• Day 4: Tests + integration + fixes
• Day 5: Reviews, finalization, reflection

1. Domain Model Design

Before writing code, you will design the core learning-content data model for the app.

Application Requirements

You are building a health-focused learning app that helps parents learn skills through structured content:

• Parents register and are assigned to one or more Courses they must complete.
• Each Course consists of roughly 10 Modules.
• A Module may belong to more than one course.
• A Module is composed of an ordered sequence of Posts.
• Posts can have multiple types: video, attachment, quiz, default.
• User progress is tracked across the Course to which they are assigned.

1.1 Deliverable: Model drawing + design document

Create a diagram of your proposed models and relationships:

• Must include:
  • Entities (tables/models) you propose
  • Relationships (one-to-many, many-to-many, etc.)
  • Key attributes (fields) for each entity, including data types and which attributes are mandatory vs optional
  • Primary keys and foreign keys (at a conceptual level)
• Format: Hand-drawn (photo) OR digital (draw.io / Excalidraw / Figma / etc.)
• Save as: hw02_model_design.pdf or hw02_model_design.png

Create a design document (docs/hw02_design.md, 200–400 words) explaining:

• Key modeling decisions (including how you represented module reuse across courses)
• How relationships and ordering were handled
• Tradeoffs made and alternatives considered
• Any parts that were more tricky than others and why you ultimately made the decisions you did

Submission:

• Add the diagram file to your PR (in a /docs folder) OR include it in your PR description (linked image)
• Create docs/hw02_design.md during the design phase, then refine and finalize it after implementation

2. Implement Module CRUD

In this part, you will implement only the Module resource end-to-end:

• SQLAlchemy model(s) as needed
• Pydantic schemas
• Routes (CRUD endpoints)
• Contract-level API tests

You are not implementing full course assignment logic, post creation, or progress tracking yet — but your design should anticipate them.

2.1. Required endpoints (Module resource)

Implement the following endpoints in backend/routes/modules.py:

Endpoint	Method	Description
/api/modules	GET	List modules accessible to the user
/api/modules/{id}	GET	Get a single module
/api/modules	POST	Create a new module
/api/modules/{id}	PATCH	Update a module
/api/modules/{id}	DELETE	Delete a module

Assumptions (unless your starter code dictates otherwise):

• You must require authentication for all module endpoints.
• You should enforce role-based behavior if the existing app uses roles (e.g., only admins/managers can create/delete).
• Modules should have at minimum:
  • id
  • title
  • description (optional)
  • any fields already implied by the starter code

2.2. Write behavior contracts using GitHub Issues

For each endpoint, create a GitHub issue with a behavior contract (as in HW1). Each issue should include:

1. Input: params + request body
2. Behavior: step-by-step what happens
3. Output: status code + response shape
4. Errors: common failure cases (401/403/404/422/400)

Submission: Create one GitHub issue per endpoint (5 issues total) in your team’s repository. Use clear titles like “Contract: GET /api/modules” or “Contract: POST /api/modules”.

2.3. Implement data model changes (as needed)

You will likely need new/updated models to support future work. At minimum, implement what your Module endpoints needs right now.

Design requirements you should plan for (but may implement partially):

• A module can belong to multiple courses (many-to-many)
• A module contains ordered posts (ordering must be representable)

You are not required to build all endpoints for those relationships yet, but your schema should not block future work.

2.4. Write tests (contract-level)

Create tests/test_modules.py and write contract-level tests for each endpoint.

Minimum coverage per endpoint:

1. Success case (200/201/204 etc.)
2. At least 2 failure cases, such as:
   • missing/invalid input → 422
   • unauthorized → 401
   • forbidden (wrong role) → 403
   • not found → 404
   • business rule violation (if applicable) → 400

Testing constraints:

• Prefer verifying behavior through the API (not direct DB queries)
• Use existing fixtures (client, test_db, auth_headers, etc.)
• Tests should be clear, independent, and fast
• Use @pytest.mark.asyncio if your test suite is async (match the existing pattern)

2.5. Optional Enhancement

Update backend/scripts/populate.py to create sample modules when seeding the database. This ensures you can test your endpoints with real data. You may want to create a CSV file in backend/scripts/sample_data/ (similar to courses.csv) or add modules programmatically in the script.

3. Submission and Reflection

3.1 Team Deliverables

1. Code submitted via pull requests and merged into main by the deadline.
2. ER/model diagram (from section 1.1)
3. Design document (docs/hw02_design.md, from section 1.1)
4. Behavior contracts as GitHub issues (from section 2.2, one per endpoint)

3.2 Individual Reflection

Each student must complete an individual reflection in their shared Google document (LastName_FirstName_373).

Under today’s date, respond (200–350 words total):

1. What design decision felt most important in this assignment, and why?
2. What was hardest about implementing Module CRUD cleanly?
3. What did you learn from reviewing teammates’ work?

Paste your reflection into the Weekly Reflection Form as usual.

Submission Checklist

Team Requirements

Design

Implementation

Process

Individual Submission