Backend Overview

FastAPI backend with SQLModel, designed for rapid development and production deployment.

🗄️ Database Models (SQLModel)

Type-safe models that work as both database tables and API schemas.

# Base model (shared fields)
class TaskBase(ModelWithIdAndTimestamps):
    title: str
    completed: bool = Field(default=False)
    user_id: UUID = Field(foreign_key="user.id")

# Database table
class Task(TaskBase, table=True):
    user: User = Relationship(back_populates="tasks")

# API models (auto-generated)
CreateTaskDTO = create_create_model(TaskBase, "CreateTask")
UpdateTaskDTO = create_update_model(TaskBase, "UpdateTask")
class TaskDTO(BaseDTO, TaskBase):
    pass

What you get:

• Python classes that map directly to database tables
• Automatic relationship management
• Type-safe API serialization

Get Started: Your First Feature → | Database Operations →

---

🔌 API Development

FastAPI with automatic CRUD and OpenAPI documentation.

# Automatic CRUD endpoints
_task_crud = CRUDBaseRouter(
    model=Task,
    read_schema=TaskDTO,
    create_schema=CreateTaskDTO,
    update_schema=UpdateTaskDTO,
    prefix="/tasks",
    tags=["Tasks"],
)

router = _task_crud.get_router()
_task_crud.setup_routes()

# Custom business logic
@router.get("/my-tasks")
async def get_my_tasks(
    current_user: User | None = Depends(get_current_user), 
    db: DatabaseDep,
):
    if not current_user:
        raise HTTPException(status_code=401, detail="Not authenticated")
        
    result = await db.exec(
        select(Task).where(Task.user_id == current_user.id)
    )
    return result.all()

Built-in features:

• Interactive API docs at /docs
• Automatic TypeScript generation for frontend
• Request validation and error handling
• CRUD automation with minimal code

---

🔐 Authentication

Enterprise-ready auth with upstream integration support.

from utils.auth import get_current_user

@router.get("/protected")
async def protected_endpoint(
    current_user: User | None = Depends(get_current_user)
):
    if not current_user:
        raise HTTPException(status_code=401, detail="Not authenticated")
    
    return {"user_id": current_user.id, "email": current_user.email}

Features:

• API Gateway integration (APISIX, etc.)
• Development mode with fake user simulation
• Header-based authentication
• Type-safe user context throughout app

---

⚡ Asynchronous Workflows

Abraxas workflows for complex, long-running processes.

from abraxas import Workflow, activity

@workflow
class DataProcessingWorkflow:
    @workflow.run
    async def run(self, user_id: int) -> dict:
        # Step 1: Validate input
        await self.validate_user(user_id)
        
        # Step 2: Process data
        result = await self.process_data(user_id)
        
        # Step 3: Send notification
        await self.send_notification(user_id, result)
        
        return {"status": "completed", "processed": result}
    
    @activity
    async def validate_user(self, user_id: int):
        # Validation logic
        pass

What you can build:

• Multi-step processes with automatic retries
• Human-in-the-loop workflows
• Scheduled and event-driven automation
• Distributed processing across workers

Get Started: Workflow Development →

---

🤖 AI Integration

Mistral AI services built-in and ready to use.

from services.mistral_service import MistralServiceDep

@router.post("/chat")
async def chat_completion(
    request: ChatRequest,
    mistral: MistralServiceDep,
):
    response = await mistral.chat_completion(
        messages=request.messages,
        model="mistral-small"
    )
    return {"response": response}

AI capabilities:

• Chat completions with streaming
• Text-to-vector embeddings for search
• OCR and document processing
• Vector similarity search with pgvector

Get Started: Embeddings & Search →

---

🗃️ Services & Dependencies

Dependency injection for clean architecture.

# Service dependencies (auto-injected)
async def create_task(
    task_data: CreateTaskDTO,
    db: DatabaseDep,                    # Database session
    mistral: MistralServiceDep,         # AI service
    config: ConfigServiceDep,           # Environment config
    current_user: User = Depends(get_current_user),
):
    # Business logic with injected dependencies
    pass

Key services:

• DatabaseService: Database session management
• MistralService: AI API integration
• ConfigService: Environment configuration
• StorageService: Cloud file storage

---

🛠️ Developer Experience

Everything configured and ready for productive development.

Database migrations:

# 1. Modify models in db_models.py
# 2. Generate migration
uv run alembic revision --autogenerate -m "Add tasks table"
# 3. Apply migration  
uv run alembic upgrade head

Environment config:

# In your .env file
DATABASE_URL=postgresql://user:pass@localhost/db
MISTRAL_API_KEY=your_api_key

# Accessed in code via ConfigService
config = ConfigService()
db_url = config.get_database_url()

Built-in tools:

• Hot reload for instant feedback
• Structured logging with correlation IDs
• Health checks at /health/check
• Docker support for deployment

Get Started: Database Migrations →

---

📁 Cloud Storage

Universal storage interface for file management.

from services.storage_service import StorageServiceDep

@router.post("/upload")
async def upload_file(
    file: UploadFile,
    storage: StorageServiceDep,
):
    file_url = await storage.upload_file(
        file=file,
        bucket="documents",
        key=f"user_{user_id}/{file.filename}"
    )
    return {"url": file_url}

Supported providers:

• Amazon S3
• Google Cloud Storage
• Extensible for other providers

---

🚀 Getting Started

Build real backend features with these learning paths:

1. Build Your First Feature → - Complete CRUD with database and API
2. Database Operations → - Relationships, queries, and migrations
3. Pydantic Patterns → - Validation and data modeling
4. Database Migrations → - Schema evolution with Alembic
5. AI & Embeddings → - Semantic search and AI integration
6. Abraxas Workflows → - Async processes and automation

Start with one feature, understand the patterns, then build what you need.