Project Structure

Project Structure

├── app/
│   ├── actions/            # Business logic
│   │   ├── account.py
│   │   ├── authentication.py
│   │   ├── group.py
│   │   ├── members.py
│   │   ├── permissions.py
│   │   ├── policy.py
│   │   ├── poll.py
│   │   ├── superuser.py
│   │   └── workspace.py
│   ├── api/                # HTTP route handlers  
│   │   ├── polls.py
│   │   ├── streams.py
│   │   └── websocket.py
│   ├── exceptions/         # Custom exceptions
│   │   ├── account.py
│   │   ├── authentication.py
│   │   ├── group.py
│   │   ├── policy.py
│   │   ├── poll.py
│   │   ├── resource.py
│   │   └── workspace.py
│   ├── models/             # Data models
│   │   ├── polls.py
│   │   └── questions.py
│   ├── schemas/            # Request/response schemas
│   │   ├── polls.py
│   │   ├── questions.py
│   │   └── websocket.py
│   └── utils/              # Utility functions
│       ├── actions.py
│       ├── api_versioning.py
│       ├── api.py
│       ├── auth.py
│       ├── cli_args.py
│       ├── colored_dbg.py
│       ├── events.py
│       ├── mongo.py
│       └── streams.py
├── docker-compose.yml
├── Dockerfile
├── main.py                 # Application entry point
├── pyproject.toml         # Project configuration
├── requirements.txt       # Python dependencies
└── uv.lock               # Dependency lock file

Core Files

app.py

Contains the main FastAPI application instance. Responsible for:

• Starting the server
• Loading configuration
• Registering routes and middleware
• Database initialization

config.py

Configuration management using Pydantic Settings:

• Environment variable loading
• Default values
• Configuration validation

dependencies.py

FastAPI dependency injection functions:

• Authentication dependencies
• Database session management
• Request validation

documents.py

Database document definitions using Beanie ODM:

• User/Account models
• Workspace models
• Group models
• Poll models
• Policy models

cli.py

Command-line interface using argparse:

• Server startup commands
• Configuration setup
• OpenAPI schema generation

Architecture Layers

1. Actions Layer (actions/)

Contains business logic and data processing:

• Purpose: Implement core functionality separate from HTTP concerns
• Pattern: Each action is a pure function that takes input and returns output
• Benefits: Testable, reusable, and framework-agnostic

2. API Layer (api/)

HTTP route handlers and request/response processing:

• Purpose: Handle HTTP requests and delegate to actions
• Responsibilities: Request validation, response formatting, error handling
• Integration: Uses FastAPI decorators and depends on actions layer

3. Models Layer (models/)

Database document definitions:

• Purpose: Define data structure and relationships
• Technology: Beanie ODM (built on MongoDB)
• Features: Validation, relationships, indexes

4. Schemas Layer (schemas/)

Request and response data validation:

• Purpose: Define API contracts using Pydantic models
• Benefits: Automatic validation, serialization, and documentation
• Types: Input schemas, output schemas, update schemas

5. Utils Layer (utils/)

Shared utilities and helper functions:

• Authentication: JWT handling, OAuth strategies
• Database: Connection management, query helpers
• CLI: Command-line argument parsing
• Debugging: Colored console output

Development Workflow

1. Database Models (models/) - Define your data structure
2. Schemas (schemas/) - Define API contracts
3. Actions (actions/) - Implement business logic
4. Routes (api/) - Create HTTP endpoints
5. Tests (tests/) - Write comprehensive tests

File Naming Conventions

• Snake_case for file and function names
• PascalCase for class names
• UPPER_CASE for constants
• Descriptive names that indicate purpose

Import Structure

# Standard library imports
import os
from typing import List

# Third-party imports
from fastapi import FastAPI, Depends
from pydantic import BaseModel

# Local imports
from app.dependencies import get_current_user
from app.actions.workspace import create_workspace
from app.schemas.workspace import WorkspaceCreate