Create Python web backend reference architecture

[jonathanmach]

The goal is to create a Python web backend reference architecture that serves as a foundational project for future development. This reference project will include multiple domains/feature areas and demonstrate best practices for organizing services, repositories, and dependency injection. It will utilize a layered architecture, defining clear separation of concerns through the use of schemas, DTOs, and consistent naming conventions. The deliverable will provide a comprehensive example of scalable and maintainable backend design, serving as a guide for implementing similar solutions in production systems.

---

Requirements

• How to structure separate API use-cases (ie. user-facing API vs admin-facing API)
• Which layer to place Authorization-related logic?

---

Related Resources

• https://github.com/betaacid/FastAPI-Reference-App

[jonathanmach]

2 Major structures: by Layer vs Feature

Source: https://medium.com/@minadev/how-to-structure-our-code-b5e7b1c32c21

https://medium.com/@tanooshri24/scalable-project-structure-for-backend-applications-55636326ee37

---

/project-root
├── /src
│   ├── /api                # All API layers (REST, WebSocket, RPC, External APIs)
│   │   ├── /rest
│   │   │   ├── /user       # User-facing API routes
│   │   │   ├── /admin      # Admin backend API routes
│   │   │   └── /common     # Shared REST utilities (middleware, helpers, etc.)
│   │   ├── /websocket      # WebSocket interface implementation
│   │   ├── /rpc            # RPC interface implementation
│   │   ├── /external       # External versioned APIs
│   │   │   ├── /v1
│   │   │   └── /v2
│   │   └── /middleware     # Cross-cutting concerns (auth, logging, etc.)
│   │
│   ├── /app                # Application logic (features, modules, domains)
│   │   ├── /features
│   │   │   ├── /feature1
│   │   │   │   ├── /domain # Domain logic for feature1
│   │   │   │   ├── /infra  # Feature-specific infrastructure integrations
│   │   │   │   └── /tests  # Unit and integration tests for feature1
│   │   │   ├── /feature2
│   │   │   └── /shared     # Shared logic/utilities across features
│   │   ├── /domains        # Core business domains
│   │   │   ├── /domain1    # Domain-specific logic
│   │   │   └── /domain2
│   │   └── /services       # Application services
│   │
│   ├── /infra              # Infrastructure-specific code
│   │   ├── /db             # Database layer (ORM, migrations, repositories)
│   │   ├── /cache          # Cache layer integrations
│   │   ├── /queues         # Message queues (e.g., RabbitMQ, Kafka)
│   │   ├── /config         # Application and environment configurations
│   │   └── /utils          # General-purpose utilities and helpers
│   │
│   ├── /tests              # Comprehensive tests
│   │   ├── /unit
│   │   ├── /integration
│   │   └── /e2e            # End-to-end tests
│   │
│   └── /workers            # Background jobs and workers
│
├── /scripts                # Automation and DevOps scripts
│
├── /docs                   # Project documentation
│
├── /config                 # Centralized configuration files
│   ├── /env                # Environment-specific configurations
│   └── /overrides          # Override configurations for testing or staging
│
└── /logs                   # Log files

---

Feature-based Modular Architecture

/project-root
├── /src
│   ├── /features           # All features/modules/domains are self-contained
│   │   ├── /feature1
│   │   │   ├── /api        # Feature-specific API (REST, WebSocket, RPC, etc.)
│   │   │   ├── /domain     # Domain logic for the feature
│   │   │   ├── /services   # Application-specific logic (use cases)
│   │   │   ├── /infra      # Feature-specific infrastructure (e.g., DB, messaging)
│   │   │   ├── /tests      # Feature-specific unit and integration tests
│   │   │   └── /ui         # Optional UI components (if applicable)
│   │   ├── /feature2
│   │   │   ├── /api
│   │   │   ├── /domain
│   │   │   ├── /services
│   │   │   ├── /infra
│   │   │   └── /tests
│   │   └── /shared         # Shared utilities or logic (cross-cutting concerns)
│   │       ├── /middleware
│   │       ├── /helpers
│   │       └── /constants
│   │
│   ├── /api                # Centralized API entry points (if needed)
│   │   ├── /rest
│   │   ├── /rpc
│   │   ├── /websocket
│   │   └── /external
│   │
│   ├── /infra              # Infrastructure layer (shared across features)
│   │   ├── /db             # Centralized database repositories and migrations
│   │   ├── /cache          # Caching infrastructure
│   │   ├── /queues         # Message queues
│   │   └── /config         # Configuration and environment-specific settings
│   │
│   ├── /tests              # Global tests (e.g., e2e, performance tests)
│   │   ├── /e2e
│   │   ├── /integration
│   │   └── /performance
│   │
│   ├── /workers            # Background jobs and workers
│   │   ├── /feature1_worker
│   │   └── /feature2_worker
│   │
│   ├── /ui                 # Optional folder for UI-related components (e.g., React)
│   │
└── /docs                   # Project documentation

[jonathanmach]

Borrow insights from Nest.js: https://github.com/jonathanmach/the-mastery-lab/blob/main/fakeflix-foundations-of-enterprise-software-development/README.md#modules