RecipeBox Project Vision

Welcome to the start of your SDD Capstone Project. Throughout this course, you have learned the principles of Spec-Driven Development (SDD) and how to use AI to speed up your coding. Now, it is time to put everything together to build a professional, production-ready application.

In this unit, we are building RecipeBox. This is more than just a simple list of recipes. It is a tool for home cooks to:

• Manage Recipes: Store ingredients, steps, and tags.
• Plan Meals: Assign recipes to specific days of the week.
• Generate Shopping Lists: Automatically combine ingredients from a meal plan into a single list, grouped by category.
• Track Nutrition: Fetch and calculate calories and macros.

To build this, we will use a modern technical stack: FastAPI for the web framework, PostgreSQL to store data, and Redis as a cache for nutrition data and as a message broker for background job queues. On CodeSignal, these libraries are usually pre-installed, but knowing the stack helps you understand how the "engine" of your app works. In the hands-on practice exercises on CodeSignal, we use SQLite instead of PostgreSQL to keep the environment simple. Because we use SQLAlchemy as our ORM, the patterns and code you write are identical — switching to PostgreSQL in production requires only changing the connection string.

This lesson walks through the full planning pipeline in four phases. Don't worry about memorizing every detail now; the practices will give you hands-on experience with each phase.

Before we dive into the code, let's quickly remember the workflow we have been practicing. In SDD, we never start by writing code. Instead, we follow a strict sequence:

1. Requirements: Define what we want.
2. Specification: Detail exactly how it should work.
3. Implementation: Use AI agents to write the code based on the spec.

In our previous lessons, you learned about Orchestration. This is the process where you act as the manager. You don't just ask an AI to "build the whole app." You break the project into small, atomic tasks and use a task-executor agent to finish them one by one. This ensures the AI stays focused and doesn't get "confused" by too much information at once.

Every great project starts with an idea. We begin by creating a file called informal-requirements.txt. It contains a few paragraphs describing the app in plain English. For RecipeBox, it might look like this:

Users need to manage recipes and plan meals for the week. 
Recipes have ingredients with amounts and units. 
Meal plans assign recipes to days. 
Shopping lists should be generated automatically from meal plans.

Next, we use an AI to turn this into a Product Requirements Document (PRD). This document is a formal version of your idea. It includes "Success Metrics" (how we know the app works) and "Constraints" (rules we must follow, like using PostgreSQL).

The most important part of this phase is the Domain Model. This is a map of how your data fits together. Let's look at how we build the relationship between Recipes and Ingredients.

First, we define a Recipe.

# A Recipe has a name and basic info
class Recipe:
    id: uuid
    name: str
    description: str

Next, we need Ingredients. But a recipe doesn't just "have" an ingredient; it needs a specific amount of that ingredient.

# An Ingredient is a general item like "Flour"
class Ingredient:
    id: uuid
    name: str
    category: str # e.g., "Baking"

Finally, we connect them using a "join table" called RecipeIngredient. This stores the connection and the amount.

# This connects a specific Recipe to a specific Ingredient
class RecipeIngredient:
    recipe_id: uuid
    ingredient_id: uuid
    amount: decimal
    unit: str # e.g., "cups"

By defining these relationships early, we ensure our database is organized and efficient.

Now that we have a PRD and a data map, we need a Functional Specification. Think of this as the "Instruction Manual" for the AI. It lists every API endpoint (like POST /recipes) and the exact rules for calculation. Once refined, this functional specification becomes a single consolidated file (specification.md) that serves as the source of truth for all implementation work in later phases.

For RecipeBox, we have complex rules like Serving Scaling. If a recipe is for 4 people, but you want to cook for 2, the app must divide every ingredient amount by 2.

To make sure our spec is high quality, we grade it on five dimensions:

1. Clarity: Is every field type exact (e.g., decimal(10,2))?
2. Completeness: Are all 7 data models and 15+ endpoints listed?
3. Testability: Are there "Given/When/Then" examples?
4. Consistency: Do all endpoints use the same naming style?
5. Appropriate Abstraction: Does it describe what the system does, not how to write the code?

Each dimension is graded out of 20 points for a total of 100. In the capstone, we aim for a score of 85/100. If your spec is vague, you must refine it. For example, instead of saying "calculate nutrition," you should specify: "Sum the calories of all ingredients, multiplied by the serving factor."

With the requirements and specification complete, we now shift from defining what the system does to planning how it will be built.

We create a Technical Plan. This defines our architecture. For RecipeBox, we use the Repository Pattern. This means our API doesn't talk to the database directly. Instead, it talks to a "Repository" file that handles the data. This keeps our code clean and easy to test.

The most critical file you will create is AGENTS.md. This is your project's Constitution. It contains the "laws" that every AI agent must follow.

# AGENTS.md Guidelines

- **Tech Stack:** FastAPI, SQLAlchemy, PostgreSQL.
- **Code Style:** Use type hints and Google-style docstrings.
- **Architecture:** All database access must go through the /repositories directory.
- **Testing:** Every task must have 90%+ test coverage.

When an agent starts a task, it reads this file first. This ensures that even if different agents work on different parts of the app, the code looks like it was written by the same person.

In a large project, one AI isn't enough. We create a "workforce" of specialized agents in the .codex/agents/ directory. Each agent has a specific job:

• task-executor: The builder who writes the code.
• test-enhancer: The auditor who adds extra tests to find bugs.
• recipe-validator: The expert who checks if the math for servings and units is correct.
• doc-updater: The writer who keeps the documentation current.

Finally, we break the project into 23 atomic tasks. An "atomic" task is a small piece of work that takes 10–30 minutes end-to-end (including task definition, AI generation, and human review) and affects 3 or fewer files.

The last planning concept to understand is how these tasks can be executed efficiently across agents. We also identify Parallel Workflows. For example, once the "Foundation" (database setup) is done, one agent can work on the Recipe API while another agent works on the Meal Planning system at the same time. This is how professional teams build software quickly.

This lesson introduces the RecipeBox capstone project, focusing on the planning phase of Spec-Driven Development using a Python technical stack. Students learn to transform informal requirements into formal specifications, design domain models using SQLAlchemy, and establish a project constitution in AGENTS.md to guide AI agents. By decomposing the project into atomic tasks and defining a robust technical blueprint with FastAPI and PostgreSQL, learners prepare to build a professional, production-ready application.