Module Structure

This document explains the canonical module structure for backend entities.

Standard Entity Module Pattern

Every database entity follows this structure:

database/{entity}/
├── __init__.py          # Empty or module exports (REQUIRED)
├── models.py            # SQLAlchemy models (REQUIRED)
├── schemas.py           # Pydantic schemas (REQUIRED)
├── crud.py              # CRUD operations (REQUIRED)
└── apis.py              # FastAPI routes (REQUIRED)
└── docs/                # Module documentation (REQUIRED)
    ├── readme.md        # Always present
    ├── api.md           # Optional - if module has API endpoints
    └── usage.md         # Optional - complex modules only

Why This Structure?

1. Separation of Concerns:

   • models.py: Defines the database schema (SQLAlchemy).
   • schemas.py: Defines data validation and serialization (Pydantic).
   • crud.py: Handles database interaction and business logic.
   • apis.py: Handles HTTP requests, authentication, and response formatting.

2. Reusability:

   • CRUD functions can be called by other modules without going through HTTP.
   • Schemas can be shared between different parts of the application.

3. Consistency:

   • Every module looks the same, making it easy for developers to navigate.

4. Scalability:

   • As the application grows, new entities can be added without cluttering a single file.

Wiring It Together

1. Importing Models:

   • main.py (or a central database.py) imports all models to ensure they are registered with SQLAlchemy/Alembic.

2. Registering Routers:

   • main.py includes the router from apis.py.

# main.py
from database.entities.apis import router as entities_router

app.include_router(entities_router)

Required Files Breakdown

models.py

Contains the SQLAlchemy model definition.

• Inherits from Base.
• Defines table name (snake_case, plural).
• Defines columns with types.
• Defines relationships.

schemas.py

Contains Pydantic schemas for request and response validation.

• EntityCreate: For creation requests (input validation, sanitization).
• EntityUpdate: For update requests (optional fields).
• EntityResponse: For API responses (ORM mode enabled).

crud.py

Contains async functions for database operations.

• create_entity: Creates a new record.
• get_entity: Retrieves a record by ID.
• update_entity: Updates a record.
• delete_entity: Deletes a record.
• get_entities_by_criteria: Lists records based on filters.

Standards:

• CRUD functions should return domain objects / primitives (e.g., ORM instances, Pydantic domain models, dicts/lists) so they can be reused outside HTTP.
• CRUD functions must not return HTTP response envelopes (keep StandardResponse / StandardListResponse in the API layer).

apis.py

Contains FastAPI route handlers.

• Defines the APIRouter.
• Dependency injection for database session and current user.
• Authentication and authorization checks.
• Calls CRUD functions.
• Returns standardized responses.

docs/readme.md

Contains documentation for the module.

• Purpose of the entity.
• Key features.
• Dependencies.
• Usage examples.