Serverpod Architecture & Development Guide
Overview
Serverpod splits projects into three modules: server, client, and shared. Models defined in .spy.yaml files generate type-safe Dart classes and database migrations via serverpod generate.
Process
High-Level Workflow
Phase 1: Research & Modeling
1.1 Understand Project Structure
Serverpod separates code into server, client, and shared modules. Endpoint logic lives in server; generated client code goes into client.
1.2 Define Data Models
Define database models using .spy.yaml files, then run serverpod generate to produce Dart classes and database migrations. Use explicit foreign key mappings for relational tables.
Phase 2: Implementation
2.1 Develop Endpoints
Implement business logic inside endpoint classes. Use session parameters for authentication context, built-in caching, and native JSON serialization.
2.2 Authentication & Caching
Use the serverpod_auth module for token-based authentication. Configure Redis for caching to reduce repeated database queries.
2.3 Database-less Backends (Serverpod Mini)
Use Serverpod Mini when you only need proxy/BFF endpoints without a PostgreSQL database.
Phase 3: Deployment
3.1 Docker & Production
Use docker-compose to orchestrate local and production environments. Configure environment variables for credentials and connection strings.
Reference Files
Documentation Library
Core Framework (Load First)
Schema and Logic (Load During Phase 1/2)
Security, Scaling & Testing (Load During Phase 2/3)
1---2name: developing-serverpod-backend3description: Develops full-stack Dart backends using the Serverpod framework with PostgreSQL, Redis, and Docker. Use when building type-safe API endpoints, defining YAML data models, configuring Serverpod auth, writing server-side tests, running database migrations, deploying to Docker/AWS/GCP, or using Serverpod Mini for database-less BFF proxy endpoints.4---5
6# Serverpod Architecture & Development Guide
7
8## Overview
9
10Serverpod splits projects into three modules: `server`, `client`, and `shared`. Models defined in `.spy.yaml` files generate type-safe Dart classes and database migrations via `serverpod generate`.
11
12---
13
14# Process
15
16## High-Level Workflow
17
18### Phase 1: Research & Modeling
19
20#### 1.1 Understand Project Structure
21Serverpod separates code into `server`, `client`, and `shared` modules. Endpoint logic lives in `server`; generated client code goes into `client`.
22
23#### 1.2 Define Data Models
24Define database models using `.spy.yaml` files, then run `serverpod generate` to produce Dart classes and database migrations. Use explicit foreign key mappings for relational tables.
25- [Core Architecture & Models Guide](./references/core-and-models.md) - YAML model definitions, project structure, and relationship mapping.
26
27---
28
29### Phase 2: Implementation
30
31#### 2.1 Develop Endpoints
32Implement business logic inside endpoint classes. Use session parameters for authentication context, built-in caching, and native JSON serialization.
33- [Endpoints & Database Guide](./references/endpoints-and-database.md) - Typed ORM queries, transactions, and API endpoint patterns.
34
35#### 2.2 Authentication & Caching
36Use the `serverpod_auth` module for token-based authentication. Configure Redis for caching to reduce repeated database queries.
37- [Authentication & Caching Guide](./references/auth-and-caching.md) - `serverpod_auth` setup, endpoint protection, and Redis caching.
38
39#### 2.3 Database-less Backends (Serverpod Mini)
40Use Serverpod Mini when you only need proxy/BFF endpoints without a PostgreSQL database.
41- [Serverpod Mini Guide](./references/serverpod-mini.md) - Lightweight API routing without database dependencies.
42
43---
44
45### Phase 3: Deployment
46
47#### 3.1 Docker & Production
48Use `docker-compose` to orchestrate local and production environments. Configure environment variables for credentials and connection strings.
49- [Deployment & Docker Guide](./references/deployment-and-docker.md) - Production Dockerfiles, AWS/GCP deployment, environment configuration.
50
51---
52
53# Reference Files
54
55## Documentation Library
56
57### Core Framework (Load First)
58- [Serverpod Overview](./references/overview.md) - Setup, project structure, and architecture decisions.
59
60### Schema and Logic (Load During Phase 1/2)
61- [Core Architecture & Models Guide](./references/core-and-models.md) - YAML models, database schema, directory structure.
62- [Endpoints & Database Guide](./references/endpoints-and-database.md) - ORM, typed queries, API endpoints.
63- [Serverpod Mini Guide](./references/serverpod-mini.md) - Database-less proxy routing.
64
65### Security, Scaling & Testing (Load During Phase 2/3)
66- [Authentication & Caching Guide](./references/auth-and-caching.md) - `serverpod_auth`, endpoint protection, Redis caching.
67- [Deployment & Docker Guide](./references/deployment-and-docker.md) - AWS/GCP, Docker, environment management.
68- [Testing Guide](./references/serverpod-testing.md) - Isolated database testing, endpoint simulation, auto-generated test utilities.
aibot88