Skip to main content
Entirius
AI platform for e-commerce
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

ADR-001: Modular Monolith Architecture

Status

Status: Accepted
Date: 2025-06-17
Authors: Piotr Brzozowski
Reviewers: Piotr Brzozowski

Decision

Adopt modular monolith architecture as the primary architectural pattern for Entirius platform. Single deployable unit with well-defined internal modules and clear boundaries enables rapid development while maintaining architectural discipline.

Quick Reference

Architecture Guidelines:

  • Single deployable unit with clear module boundaries
  • Each module should have well-defined interfaces
  • Use Django apps to represent modules
  • Database schema should reflect module boundaries
  • Modules communicate through well-defined APIs or events
  • Plan for future service extraction if complexity justifies it

Key Commands:

# Create new module
python manage.py startapp module_name

# Run complete application
python manage.py runserver

# Database migrations for modular design
python manage.py makemigrations
python manage.py migrate

Context

Entirius is an e-commerce AI platform in early development phase. We need to choose the primary architectural pattern that will guide the system design and implementation. The decision impacts deployment strategy, development complexity, operational overhead, and future scalability options.

Key considerations:

  • Early-stage project with evolving requirements
  • Small development team
  • Need for rapid prototyping and iteration
  • Future scalability requirements unknown
  • PostgreSQL as primary database
  • Python 3 as primary programming language

Considered Options

Option 1: Microservices Architecture

  • Description: Decompose the system into small, independent services communicating via APIs
  • Pros:
    • Independent scaling of components
    • Technology diversity possible
    • Team autonomy for different services
    • Fault isolation
  • Cons:
    • High operational complexity
    • Network latency and reliability issues
    • Distributed system challenges (debugging, monitoring)
    • Overhead for small team
    • Complex deployment pipeline
  • Impact on system: Requires sophisticated infrastructure, monitoring, and deployment tools

Option 2: Traditional Monolith

  • Description: Single codebase with all functionality in one deployable unit
  • Pros:
    • Simple deployment and operations
    • Easy debugging and testing
    • Strong consistency guarantees
    • Low operational overhead
  • Cons:
    • Tight coupling between components
    • Difficult to scale individual parts
    • Technology lock-in
    • Risk of becoming unmaintainable
  • Impact on system: Risk of creating a “big ball of mud” architecture

Option 3: Modular Monolith

  • Description: Single deployable unit with well-defined internal modules and clear boundaries
  • Pros:
    • Simple deployment like traditional monolith
    • Clear module boundaries and separation of concerns
    • Easy refactoring and testing
    • Can evolve to microservices if needed
    • Lower operational complexity
    • Strong consistency within modules
  • Cons:
    • Requires discipline to maintain module boundaries
    • All modules share same technology stack
    • Entire application scales as unit
  • Impact on system: Enables clean architecture with option to extract services later

Rationale

Chosen option: Modular Monolith

Key decision factors:

  • Development velocity: Enables rapid development and iteration without microservices overhead
  • Operational simplicity: Single deployment unit reduces operational complexity for small team
  • Architectural discipline: Forces good modular design without distributed system complexity
  • Future flexibility: Can extract modules to microservices when business requirements justify the complexity
  • Team size: Optimal for single developer/small team scenario
  • Technology consistency: Leverages Python/PostgreSQL expertise without forcing premature technology decisions
  • Testing simplicity: Easier integration testing without network boundaries
  • Risk analysis: Low risk approach with proven patterns and clear evolution path
  • Impact on business goals: Enables faster time-to-market and reduced operational overhead
  • Compatibility with existing architecture: Aligns with Django ecosystem and single database approach
  • ADR-002: API framework aligns with modular monolith architecture

References