FastAPI MVS Architecture

This document outlines the Model-View-Service (MVS) architecture implemented in this FastAPI application.

FastOpp provides an opinionated framework for FastAPI with the following features:

admin panel similar to Django with role-based authentication

SQL database with Django-inspired models and migrations

Django-style HTML templates with modern UI components

API endpoints to connect to other frontend frameworks

auto-generated documentation for API endpoints

oppman.py management tool with some functionality similar to Django manage

Architecture Overview

The application has been refactored from a monolithic main.py file into a well-organized structure that separates concerns and improves maintainability.

Directory Structure

fastopp/
├── main.py                # New refactored entry point (MVS Architecture)
├── routes/                # Route handlers (View layer)
│   ├── __init__.py
│   ├── pages.py          # Page rendering routes
│   ├── auth.py           # Authentication routes
│   ├── api.py            # API data endpoints
│   └── webinar.py        # Webinar management routes
├── services/             # Business logic (Service layer)
│   ├── __init__.py
│   ├── product_service.py
│   └── webinar_service.py
├── models.py             # Data models (Model layer)
├── db.py                 # Database configuration
├── auth.py               # Authentication utilities
└── admin/                # Admin interface

Components

Functional Concept Component Django Equivalent
Production Web Server FastAPI + uvicorn (for loads < 1,000 concurrent connections) NGINX + Gunicorn
Development Web Server uvicorn manage.py runserver in development. Django Framework
Development SQL Database SQLite SQLite
Production SQL Database PostgreSQL with pgvector PostgreSQL + pgvector, asyncpg
User Management FastAPI Users Django Admin
Database Management SQLAdmin + Template Django Admin
Authentication Custom JWT + Session Auth (with database user verification and FastAPI Users password hashing) Django Admin Auth

Layer Responsibilities

1. Model Layer (models.py)

Define data structures and database models

  • • SQLModel/SQLAlchemy model definitions
  • • Data validation and constraints
  • • Database schema representation

2. View Layer (routes/)

Handle HTTP requests and responses

  • • Route definitions and HTTP method handling
  • • Request/response formatting
  • • Input validation and error handling

3. Service Layer (services/)

Business logic and data operations

  • • Database operations
  • • Business rules implementation
  • • Data transformation

Benefits of This Architecture

1. Separation of Concerns

  • • Routes handle HTTP concerns only
  • • Services contain business logic
  • • Models focus on data structure

2. Maintainability

  • • Smaller, focused files (50-100 lines each vs 552 lines)
  • • Clear responsibility boundaries
  • • Easier to locate and modify specific functionality

3. Testability

  • • Services can be unit tested independently
  • • Routes can be tested with mocked services
  • • Clear interfaces between layers

4. Reusability

  • • Services can be used by multiple routes
  • • Business logic is centralized
  • • Consistent error handling

5. Scalability

  • • Easy to add new route modules
  • • Services can be extended without affecting routes
  • • Clear patterns for new features

Migration Guide

The original main.py contained 552 lines of mixed responsibilities. The new structure provides:

Before: Monolithic Structure

  • • 552 lines of mixed responsibilities
  • • Database operations in route handlers
  • • File handling logic in routes
  • • Business logic scattered throughout

After: MVS Architecture

  • • Routes: 20-50 lines each, focused on HTTP handling
  • • Services: 50-100 lines each, focused on business logic
  • • Main: 60 lines, focused on app configuration
  • • Clear separation of concerns