Core Concepts

Understand the key concepts behind Builder Backend.

Projects

A project is a single backend application you're building.

One project = one generated FastAPI application.

Each project has:

Name (e.g., "E-commerce API")
Data model (entities, fields, relations)
Optional features (auth, payments, storage, deployment config)
Generation history

Example: You might have projects named "Blog", "E-commerce", "CRM".

Entities

An entity is like a database table or a resource in your API.

Examples: User, Post, Product, Order, Comment

Each entity becomes:

A database table (via Alembic migration)
A SQLAlchemy model (app/models/post.py)
CRUD API endpoints (GET /posts, POST /posts, etc.)

Entity properties:

Name: Singular, PascalCase (Post, not Posts)
Fields: The columns/attributes
API options: Which operations are enabled (list, create, update, delete)

Fields

Fields are the columns of an entity.

Supported types:

string - varchar (configurable max_length)
text - unlimited text
integer - whole numbers
float - decimal numbers
boolean - true/false
date - date only (YYYY-MM-DD)
datetime - timestamp with timezone
uuid - UUIDs (often for IDs)
json - JSONB (PostgreSQL)
file - file uploads (requires storage feature)

Field properties:

required - can't be null
unique - no duplicates
default_value - value if not provided
min/max - validation (for numbers/strings)

Example:

{
  "name": "email",
  "type": "string",
  "required": true,
  "unique": true,
  "max_length": 255
}

Relations

Relations connect entities (foreign keys).

Types:

one-to-many - One post has many comments
many-to-one - Many comments belong to one post
many-to-many - Users can like many posts, posts can be liked by many users

Example: Comment → Post (many-to-one)

{
  "from_entity_id": "comment_id",
  "to_entity_id": "post_id",
  "type": "many_to_one",
  "name": "post"
}

This adds a post_id field to Comment and generates:

GET /posts/{id}/comments - list comments for a post
Validation: can't create comment without valid post_id

Spec

The spec is the complete JSON representation of your project.

What's in a spec:

All entities and their fields
All relations
Auth configuration (if enabled)
Keycloak settings (if using SSO)
Payments config (if enabled)
Storage config (if enabled)
Authorization model (RBAC/ABAC/PBAC)
Deployment settings

Get your spec:

curl -X GET https://api.builder.dumbpotato.com/projects/{id}/spec \
  -H "Authorization: Bearer $TOKEN"

Upload a spec:

curl -X PUT https://api.builder.dumbpotato.com/projects/{id}/spec \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @spec.json

Why it matters:

Version control: Save specs in Git
Templates: Reuse specs across projects
CI/CD: Automate generation from a spec file

Validation

Validation checks your project for errors before generation.

Common issues caught:

Circular relations (A → B → A)
Missing required fields
Invalid field types
Auth enabled but no roles defined
Payments configured but no entity to charge

Validate:

POST /projects/{id}/validate

Response:

{
  "valid": false,
  "issues": [
    {
      "code": "circular_relation",
      "message": "Circular relation detected: Post → Comment → Post",
      "severity": "error",
      "fix": "Remove one of the relations or use a junction table"
    }
  ]
}

Dashboard shows issues with one-click fixes.

Generation

Generation is the process of creating your FastAPI project from the spec.

What gets generated:

app/ - FastAPI application code
app/models/ - SQLAlchemy models
app/api/ - CRUD endpoints
alembic/ - Database migrations
tests/ - Pytest test suite
docker-compose.yml - Local dev environment
Dockerfile - Production container
.env.example - Environment variables template
README.md - Setup instructions

Generated code is:

✅ Clean and readable
✅ Fully typed (mypy passes)
✅ Tested (pytest suite included)
✅ Production-ready
✅ Yours to modify (MIT license)

Generation process:

Click "Generate" or call POST /projects/{id}/generate/preview
See file tree preview
Download: GET /projects/{id}/generate/download
Get a ZIP file

Generations are recorded - see history: GET /projects/{id}/generations

Dashboard Tour

1. Overview

Project status
What's configured
Next steps checklist
Validation issues (if any)

2. Data Model

List all entities
Add/edit entities
Add/edit relations
See entity graph

3. Authentication (optional)

Enable built-in auth or Keycloak
Configure SMTP (email verification)
Configure SMS (phone verification)
Custom registration fields
Multi-tenancy

4. Keycloak (if enabled)

SSO settings
Identity providers (Google, Microsoft, GitHub)
Realm configuration

5. Roles & Access (RBAC mode)

Define roles
Set permissions per entity
Row-level security rules

6. Authorization (ABAC/PBAC mode)

Choose authorization model
Define policies
Simulate access decisions

7. Payments (optional)

Enable Stripe or Razorpay
Configure refund workflow
Sizing calculator

8. File Storage (optional)

Enable S3/MinIO storage
Malware scanning (ClamAV)
File field type

9. Observability (optional)

OpenTelemetry traces
Metrics export
Sampling configuration

10. Deploy (optional)

Choose cloud (AWS/Azure/GCP)
Environment setup
CI/CD pipeline generation

11. Generate

Preview file tree
Download ZIP
See generation history

Dashboard vs API

Task	Dashboard	API
Quick prototyping	✅ Faster	Slower
Bulk operations	Manual	✅ Scripted
CI/CD	No	✅ Yes
Visual feedback	✅ Yes	No
Team collaboration	✅ Yes	Via spec files
Automation	No	✅ Yes

Best practice: Use dashboard to design, API to automate.

Authentication vs Authorization

Authentication = "Who are you?"

Sign up, log in, JWT tokens
Email/SMS verification
Password reset
Keycloak SSO

Configuration: /projects/{id}/auth or Keycloak section

Authorization = "What can you do?"

Roles and permissions
RBAC (role-based)
ABAC (attribute-based)
PBAC (policy-based)
Row-level security

Configuration: /projects/{id}/authorization

You can have auth without complex authorization (everyone can do everything) or authorization without auth (public API with rate limits).

Generated Project Lifecycle

Define - design your data model in dashboard/API
Validate - catch errors before generation
Generate - create the FastAPI project
Download - get ZIP file
Customize - modify generated code (it's yours!)
Deploy - use included Terraform/CI/CD
Maintain - regenerate when spec changes, merge customizations

Important: Generated code is a starting point, not a black box. You own it, modify it, deploy it.

What Gets Updated in Regeneration

If you regenerate after changing the spec:

Always regenerated (overwritten):

app/models/*.py - entity models
alembic/versions/*.py - migrations
app/api/*.py - CRUD endpoints (if you didn't customize)

Never overwritten (safe to edit):

.env - your secrets
Custom business logic you add
Tests you write (beyond generated ones)

Best practice: Keep generated CRUD separate from your custom logic. Add custom routes in new files.

Limits & Constraints

Current limits:

Max entities per project: No hard limit (recommended < 100)
Max fields per entity: No hard limit (recommended < 50)
Max relations: No hard limit
Project name: 1-100 characters
Entity name: 1-50 characters, PascalCase
Field name: 1-50 characters, snake_case

Validation prevents:

Circular relations
Relations across projects
Duplicate entity/field names
Reserved keywords (id, created_at, updated_at)

Next Steps

Builder Backend supports advanced features like authentication, payments, file storage, and more. Explore the documentation to learn about specific features.

API Reference - complete endpoint docs

Projects​

Entities​

Fields​

Relations​

Spec​

Validation​

Generation​

Dashboard Tour​

Sidebar Sections​

1. Overview​

2. Data Model​

3. Authentication (optional)​

4. Keycloak (if enabled)​

5. Roles & Access (RBAC mode)​

6. Authorization (ABAC/PBAC mode)​

7. Payments (optional)​

8. File Storage (optional)​

9. Observability (optional)​

10. Deploy (optional)​

11. Generate​

Dashboard vs API​

Authentication vs Authorization​

Authentication = "Who are you?"​

Authorization = "What can you do?"​

Generated Project Lifecycle​

What Gets Updated in Regeneration​

Limits & Constraints​

Next Steps​