Module 2: Data Layer#

Overview#

Every table in this backend and every request/response shape flows through this module. You'll go table by table through all 9 SQLAlchemy models — including the cascade rules that quietly delete a lot of data when an agent is removed — then all 27 Pydantic schemas that validate and serialize everything the API touches, then a map of the five services that own the actual business logic.

What You'll Learn#

• Every column, relationship, and cascade rule on all 9 models (Agent, Message, AgentRun, Task, ToolCall, Document, DocumentChunk, WorkflowRun, WorkflowStep)
• Why several numeric-looking fields (estimated_cost, quality_score) are stored as String, and what that costs downstream
• All 27 Pydantic schemas and the request/response contract they enforce
• The service layer's job: keep business logic out of routers and out of the database layer

Prerequisites#

• Module 1: Foundation — you need the layered architecture and request lifecycle in place first

Lessons in This Module#

Learning Outcomes#

By the end of this module you can:

• Draw the entity-relationship structure of all 9 tables from memory
• Explain what happens to Message, Task, ToolCall, Document, and WorkflowRun rows when an Agent is deleted
• Explain why AgentCreate and AgentResponse are two separate schemas instead of one
• Name all five services and, in one sentence each, what they own

Start Module → Back to Module 1