ARCHITECTURE & DESIGN DECISIONS

Phase 1 — Why a modular monolith, and how it’s built

February 2026 • Solen Kablo • Living Document

1. THE ARCHITECTURE: MODULAR MONOLITH

The system is a Modular Monolith — a single application with clearly separated internal modules, sharing a single database. Not microservices. Not a traditional monolith. The sweet spot in between.

Why Not Microservices?

• Scale doesn’t demand it. 10–12 machines, dozens of users, hundreds (not millions) of daily transactions. A single process handles this trivially.
• ACID transactions across modules. When an order is created, materials are calculated, work cards are generated, and stock is allocated — all in a single database transaction. With microservices, this becomes a distributed saga nightmare.
• One developer. Microservices require a team to manage deployment, monitoring, service mesh, and inter-service communication. A solo developer needs simplicity.
• Factory network, not cloud. This runs on a Mac Mini on the factory floor, not a Kubernetes cluster. One process, one database, one deploy target.

Module Boundaries

solen_backend/
├── app/
│   ├── api/                    # REST API layer
│   │   ├── auth/               # Authentication & authorization
│   │   ├── materials/          # Raw material management
│   │   ├── suppliers/          # Supplier management
│   │   ├── siparis/            # Order management
│   │   ├── production/         # Production operations
│   │   ├── teknik/             # Cable design & machines
│   │   ├── stock/              # Stock & projection
│   │   ├── ai/                 # AI chat & search
│   │   └── ...                 # 15+ more route groups
│   ├── models/                 # SQLAlchemy data models
│   │   ├── teknik/             # machines.py, cable_design.py, standards.py
│   │   ├── siparis/            # order.py, customer.py
│   │   ├── production/         # production_session.py, work_card.py
│   │   └── ...                 # material.py, supplier.py, user.py
│   ├── schemas/                # Pydantic validation schemas
│   ├── services/               # Business logic layer
│   │   ├── production_calculator.py
│   │   ├── work_card_generator.py
│   │   └── projeksiyon_service.py
│   ├── core/                   # Config, database, shared utilities
│   └── utils/                  # Production constants, helpers
├── migrations/                 # Database migration scripts
└── main.py                     # FastAPI application entry point

2. TECHNOLOGY STACK

Backend

Frontend

Infrastructure

3. DESIGN RULES

These rules were not written on day one — they crystallized over months of building, breaking, and rebuilding.

Rule 1: Turkish-First Interface

Every UI label, every error message, every notification is in Turkish. Factory operators do not speak English. The Ant Design locale is locked to Turkish. AI prompts are Turkish. The only English in the system is in code comments, variable names, and this documentation.

Rule 2: QR Code Everything

Every physical object that moves through the factory gets a QR code printed on entry. Raw copper baskets, tinned copper baskets, reels, finished cables — all scannable. The QR code links to the full history of that object in the system. This enables traceability from raw material to customer shipment.

Rule 3: Three User Roles, No More

Rule 4: Design Drives Production

The cable design is the single source of truth. When a design is created in the Cable Playground, it encodes the complete production flow — every machine step, every material requirement, every test. Orders reference designs. Work cards are generated from designs. Material calculations walk through the design’s production flow. Nothing is manually configured per-order.

Rule 5: No Premature Optimization

SQLite in development. PostgreSQL when needed. No Redis cache until there’s a measured performance problem. No message queue until synchronous processing is proven insufficient. Build the simplest thing that works, measure, then optimize.

4. API DESIGN

The backend exposes 25+ router groups, all mounted on a single FastAPI application running on port 8000. Every endpoint follows the same pattern:

@router.get("/endpoint")
async def get_something(
    db: Session = Depends(get_database),          # DB session injected
    current_user: User = Depends(get_current_user) # Auth injected
):
    # Business logic here
    return result

Key Patterns

• Dependency injection for everything. Database sessions via Depends(get_database), authentication via Depends(get_current_user), role checks via Depends(require_super_admin). No global state.
• Pydantic schemas for validation. Every request body and response has a typed schema. Create, Update, and Response variants per model. FastAPI auto-generates OpenAPI documentation from these.
• Service layer for business logic. Complex calculations (material requirements, work card generation, stock projections) live in services/, not in route handlers. Routes handle HTTP; services handle domain logic.
• Factory network CORS. The CORS configuration generates 1000+ origin combinations to support HTTP and HTTPS access from any device on the 192.168.x.x and 10.0.0.x factory networks.

Router Organization

5. DATABASE STRATEGY

The database was not designed upfront. It grew organically as each module was built. This is intentional — the domain was too complex to design a schema before understanding it.

SQLite → PostgreSQL Migration Path

SQLAlchemy ORM ensures the same Python code runs against both databases. The switch requires only changing the DATABASE_URL environment variable. Connection pooling is configured for production: 20 base connections, 40 overflow, hourly recycling, pre-ping validation.

Migration Strategy

Migrations use direct SQL scripts (not Alembic) — CREATE TABLE IF NOT EXISTS and ALTER TABLE with transaction rollback on failure. 19 migration files covering orders, users, machines, materials, stock, printing, and AI audit tables. Each migration is idempotent and can be re-run safely.

6. FRONTEND ARCHITECTURE

The frontend is a single React application built with Ant Design Pro, serving all modules through role-based menus.

Page Organization

src/pages/
├── Dashboard/              # Ana Panel — overview + AI chat
├── Lab/                    # Laboratuvar — tests, material inspection
├── Teknik/                 # Teknik — cable design, machines, standards
│   ├── CablePlayground/    # Interactive cable design tool
│   ├── Machines/           # Machine configuration
│   └── Standards/          # Test standard management
├── Siparis/                # Sipariş — orders, customers
├── Production/             # Üretim — planning, machine interfaces
│   └── Machines/           # Per-machine production UIs
│       ├── KabatelCekme/
│       ├── Kalaylama/
│       ├── IncetelCekme/
│       ├── Buncher/
│       ├── Extruder/
│       └── ElectronBeam/
├── Stok/                   # Stok — projections, product stock
├── Hammadde/               # Hammadde — material entry, orders
└── Admin/                  # Admin — printers, users, AI settings

Key Frontend Patterns

• ProTable everywhere. Ant Design Pro’s ProTable component handles server-side pagination, column filtering, expandable rows, and search. 90% of the list/detail views use this single component.
• Route-based access control. Each route has an access flag (canDashboard, canLab, canProduction, etc.). Menus auto-hide based on user role.
• Dynamic API URL. The frontend detects whether it’s running over HTTPS (proxy mode) or HTTP (direct mode) and adjusts the API base URL. On the factory network, it discovers the backend IP automatically.
• Dark mode. Full dark theme support via Ant Design CSS variables, persisted in localStorage.

7. AI INTEGRATION

A separate Python service provides AI-powered search and chat, accessible from the dashboard. The AI has read-only access to the entire database through 92 API endpoint tools.

8. NETWORK & DEPLOYMENT

The system runs on a Mac Mini on the factory floor, accessible to all devices on the local network.

Operators use mobile Chrome on phones/tablets to scan QR codes and log production. Managers use desktop browsers for order management, design, and reporting. Both access the same backend on the same network. HTTPS is enabled for mobile device security (camera access for QR scanning requires secure context).

9. THE EVOLUTION PATH

The architecture has a planned evolution path if scale ever demands it:

Each stage is a fallback, not a goal. The modular monolith should remain the architecture unless specific, measured problems demand the next stage. Don’t fix what isn’t broken.