Modular API Template (Flask & FastAPI)

A scalable, modular backend API template supporting both Flask (WSGI) and FastAPI (ASGI) architectures.
Designed for clean separation of concerns, long-term maintainability, and optional high-performance cross-language integrations (Rust, Go, C++).

This repository provides two production-ready templates sharing the same architectural philosophy:

• 🐍 Flask Modular API — battle-tested, synchronous, simple
• ⚡ FastAPI Modular API — async-first, high-performance, OpenAPI-native

---

✨ Core Philosophy

Regardless of framework, both templates follow the same principles:

• 🧩 Feature-based modular design
• 🧠 Clean separation of concerns
• 🔁 Pluggable architecture modes
• 🔐 Security-first structure
• 🧪 **Testable & maintainable codebase

---

📦 Available Templates

Template	Use When
Flask	You want simplicity, WSGI compatibility, or legacy integration
FastAPI	You want async, performance, type safety, and auto docs

Each template has its own scaffold generator and runtime entrypoint.

---

🧱 Architecture Modes (Shared by Both)

Both Flask and FastAPI support two mutually exclusive architecture modes:

✅ services mode (default)

Pure Python business logic.

• Easy to test
• Framework-agnostic
• Best for most APIs

🔗 bridge mode

External/native logic via FFI.

• Rust / Go / C++
• Performance-critical workloads
• Existing native libraries

⚠️ Choose one mode per project — do not mix services and bridge.

---

📁 Flask Template Structure

flask_modular_api_template/
├── app/
│   ├── resources/              # HTTP endpoints (controllers)
│   ├── decorators/             # Auth & validation decorators
│   ├── models/                 # ORM models (SQLAlchemy)
│   ├── schemas/                # Validation & serialization
│   ├── utils/                  # Shared utilities
│   ├── config.py               # Configuration
│   ├── errors.py               # Global error handlers
│   ├── middleware.py           # Middleware
│   ├── routes.py               # Blueprint registration
│   └── __init__.py
├── tests/
├── api.ini
├── requirements.txt
├── run.py                      # Dev entrypoint
├── wsgi.py                     # Production entrypoint
└── README.md

Flask – Services Mode

app/services/
├── authentication/
├── billing/
└── notifications/

Flask – Bridge Mode

app/bridge/
├── authentication/
│   └── authentication_rust_bridge.py
├── billing/
│   └── billing_rust_bridge.py
└── notifications/
    └── notifications_rust_bridge.py

---

📁 FastAPI Template Structure

fastapi_modular_api_template/
├── main.py                     # ASGI entrypoint
├── README.md
├── requirements.txt
├── .env
├── app/
│   ├── config.py
│   ├── dependencies.py         # Dependency injection
│   ├── middleware.py
│   ├── errors.py
│   ├── core/                   # Security & shared logic
│   │   ├── security.py
│   │   └── jwt_helpers.py
│   ├── routers/                # APIRouter per module
│   ├── schemas/                # Pydantic models
│   ├── models/                 # ORM models
│   ├── services/               # Business logic (optional)
│   └── bridge/                 # External integrations (optional)
└── tests/

FastAPI – Services Mode

app/services/
├── authentication/service.py
├── billing/service.py
└── notifications/service.py

FastAPI – Bridge Mode

app/bridge/
├── authentication/authentication_bridge.py
├── billing/billing_bridge.py
└── notifications/notifications_bridge.py

---

🔁 Request Flow Comparison

Flask

Client
  ↓
Blueprint / Resource
  ↓
Decorator / Middleware
  ↓
Service or Bridge
  ↓
Model
  ↓
Response

FastAPI

Client
  ↓
APIRouter
  ↓
Dependencies
  ↓
Service or Bridge
  ↓
Model
  ↓
Pydantic Schema
  ↓
Response

---

🚀 Quick Start (Both)

1️⃣ Generate Project

python create_flask_structure.py

python create_fast-api_structure.py

Configure inside scaffold script:

base_path = "your_project_name"
modules = ["authentication", "billing", "notifications"]
architecture_mode = "services"  # or "bridge"

2️⃣ Install Dependencies

pip install -r requirements.txt

3️⃣ Run Server

Flask

python run.py

FastAPI

uvicorn main:app --reload

---

🧪 Testing

pytest

---

🧠 Design Guidelines

Layer	Responsibility
resources / routers	HTTP & request handling
schemas	Validation & contracts
services	Business logic
bridge	Native/external logic
models	Persistence
middleware / dependencies	Cross-cutting concerns

---

🧱 Technology Stack

• Flask / FastAPI
• Pydantic / Marshmallow
• JWT Authentication
• SQLAlchemy / SQLModel
• Pytest
• Optional FFI (Rust, Go, C++)

---

📦 Repository Naming Options

• modular-api-template
• flask-fastapi-modular-api
• python-modular-backend-template

---

📜 License

MIT © Your Name