Skip to main content

​
App Structure

Maybern follows a consistent directory structure across all Django apps. This structure promotes clear separation of concerns, maintainability, and testability.

​
Directory Layout

apps/
└── sample_app/
    ├── api/                    # Public API endpoints
    │   ├── helpers/            # Helper functions for API endpoints
    │   ├── tests/              # API tests
    │   ├── dataclasses.py      # Request/response dataclasses
    │   └── exceptions.py       # API-specific exceptions
    ├── private/                # Internal implementation details
    │   ├── selectors/          # Database query functions
    │   │   ├── tests/          # Tests for selectors
    │   │   └── selector_1.py   # Individual selector files
    │   └── services/           # Business logic implementation
    │       ├── tests/          # Tests for services
    │       ├── service_1.py    # Individual service files
    │       └── service_2/      # Complex service subdirectory
    │           ├── service_2.py
    │           └── utils.py
    ├── public/                 # Publicly accessible services
    │   ├── constants.py        # Enums and constants
    │   ├── dataclasses.py      # Data structures
    │   ├── services.py         # Public service functions
    │   └── tests/              # Tests for public services
    ├── models/                 # Django ORM models
    │   ├── tests/              # Model tests
    │   └── model_1.py          # Individual model files
    ├── tasks/                  # Celery tasks
    │   ├── tests/              # Task tests
    │   └── task_1.py           # Individual task files
    ├── factories.py            # Test factories
    ├── conftest.py             # Test fixtures
    ├── apps.py                 # Django app configuration
    ├── urls.py                 # URL routing
    ├── README.md               # App documentation
    └── __init__.py             # Package initialization

​
Layer Overview

API Layer

Public endpoints that receive HTTP requests and return responses. Should be thin and delegate to services.

Public Layer

External interface for other apps. Contains services, constants, and dataclasses that can be imported by other apps.

Private Layer

Internal business logic. Contains selectors for data access and services for complex operations.

Models Layer

Django ORM models defining data structure and relationships. No business logic here.

​
Data Flow

​
Key Principles

Each layer has a specific responsibility:
  • API: Request handling, validation, response formatting
  • Public Services: External interface, orchestration
  • Private Services: Business logic implementation
  • Selectors: Data access patterns
  • Models: Data structure and relationships
Dependencies should flow inward:
  • API can import from Public
  • Public can import from Private
  • Private can import from Models
  • Models should have no app-level dependencies
Never import from Private in another app - use Public services instead.
Tests live alongside the code they test:
  • api/tests/ for API tests
  • private/selectors/tests/ for selector tests
  • private/services/tests/ for service tests
  • public/tests/ for public service tests

​
Backend Directory Structure

The overall backend structure: 
backend/
├── config/                 # Environment configuration
│   ├── .env.template       # Environment variable template
│   └── .env                # Local environment (git-ignored)
├── docker/                 # Docker configurations for ECS deployment
├── server/
│   ├── apps/               # All Django applications
│   │   ├── core/           # Core utilities and base classes
│   │   ├── clients/        # Customer/tenant management
│   │   ├── celery/         # Async task infrastructure
│   │   ├── events/         # Event system
│   │   └── ...             # Domain-specific apps
│   ├── settings/           # Django settings by environment
│   ├── locales/            # Internationalization files
│   └── urls.py             # Root URL configuration
└── integration-testing/    # Integration test data

​
Next Steps

API Development

Learn how to build APIs following our patterns.

Services & Selectors

Understand the service and selector patterns.