Architecture¶

This page gives a comprehensive architecture view of OpenSESA, from system context to runtime internals.

1. Architecture Goals¶

OpenSESA architecture is designed to support:

• lifecycle continuity across governance, engineering, assurance, and readiness
• explicit module ownership and bounded contexts
• traceability from requirements to verification evidence and release decisions
• predictable local and deployment runtime behavior through Docker Compose orchestration

2. System Context View¶

flowchart TB
    User["Engineer / Reviewer / Lead"] --> Web["OpenSESA Web UI"]
    Web --> App["Django Application"]
    App --> DB["PostgreSQL"]
    App --> Queue["Redis"]
    Queue --> Worker["Celery Worker"]
    Worker --> DB

3. Container View¶

flowchart LR
    subgraph Edge["Edge"]
      Proxy["Reverse Proxy (deployment runtime)"]
    end

    subgraph AppTier["Application Tier"]
      Django["Django app service"]
      Celery["Celery worker service"]
    end

    subgraph DataTier["Data Tier"]
      PG["PostgreSQL"]
      Redis["Redis"]
    end

    Proxy --> Django
    Django --> PG
    Django --> Redis
    Redis --> Celery
    Celery --> PG

Container Responsibilities¶

4. Runtime Modes¶

Local Runtime¶

• compose file: docker-compose.yml
• common services: app, db, redis, celery
• typical use: development, test iteration, debugging

Deploy Runtime¶

• compose file: docker-compose-deploy.yml
• includes deploy ingress proxy + deploy service naming
• typical use: production-like deployments and release validation

# local
docker compose up -d --build

# deployment runtime mode
docker compose -f docker-compose-deploy.yml up -d --build

5. Request Processing Pipeline¶

sequenceDiagram
    autonumber
    participant U as User
    participant I as Ingress
    participant M as Middleware Stack
    participant V as View Layer
    participant ORM as ORM/Model Layer
    participant DB as PostgreSQL

    U->>I: HTTP request
    I->>M: route to app
    M->>V: authenticated, policy-checked request
    V->>ORM: domain operation
    ORM->>DB: read/write
    DB-->>V: result set
    V-->>U: response payload

Middleware Layering (Conceptual)¶

OpenSESA request pipeline includes (in order-oriented groups):

• security middleware and security headers
• session/authentication middleware
• CSRF protection
• account/auth integration middleware
• MFA and login-required enforcement middleware
• HTMX support middleware

# app/app/settings.py (conceptual excerpt)
MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'core.middleware.SecurityHeadersMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'allauth.account.middleware.AccountMiddleware',
    'core.middleware.MFARequiredMiddleware',
    'core.middleware.LoginRequiredMiddleware',
    'django_htmx.middleware.HtmxMiddleware',
]

6. Routing and Module Composition¶

OpenSESA mounts domain modules by root URL prefix from app/app/urls.py.

# app/app/urls.py (representative excerpt)
urlpatterns = [
    path('', include('core.urls', namespace='core')),
    path('portfolio/', include('portfolio_mgmt.urls', namespace='portfolio_mgmt')),
    path('scope/', include('scope_mgmt.urls', namespace='scope_mgmt')),
    path('requirements-mgmt/', include('requirements_mgmt.urls', namespace='requirements_mgmt')),
    path('verification-validation/', include('verification_validation_mgmt.urls', namespace='verification_validation_mgmt')),
    path('baseline/', include('baseline_mgmt.urls', namespace='baseline_mgmt')),
    path('impact-assessment/', include('impact_assessment.urls', namespace='impact_assessment')),
    path('ops/', include('ops_mgmt.urls', namespace='ops_mgmt')),
]

Module Interaction Pattern¶

flowchart LR
    Core["core (platform shell)"]
    Gov["Governance and Scope"]
    Def["Definition and Design"]
    Ctrl["Interfaces and Requirements"]
    Evd["Verification and Assurance"]
    Rel["Baseline, Impact, Operations"]

    Core --- Gov
    Core --- Def
    Core --- Ctrl
    Core --- Evd
    Core --- Rel

    Gov --> Def
    Def --> Ctrl
    Ctrl --> Evd
    Evd --> Rel
    Ctrl --> Rel

7. Data and State Architecture¶

flowchart LR
    G["Governance State"] --> E["Engineering State"]
    E --> V["Verification and Assurance State"]
    V --> R["Release and Impact State"]
    R --> O["Operational Readiness State"]

State Ownership (High Level)¶

8. Asynchronous Architecture¶

OpenSESA uses Celery with Redis broker/result channels for background work.

sequenceDiagram
    autonumber
    participant D as Django View/Service
    participant R as Redis Broker
    participant C as Celery Worker
    participant P as PostgreSQL

    D->>R: enqueue task
    R->>C: deliver task
    C->>P: execute and persist effects
    C->>R: publish result/ack

# worker visibility
docker compose run --rm celery celery -A app inspect registered
docker compose run --rm celery celery -A app inspect ping

9. Deployment Architecture¶

flowchart TB
    Client["Client"] --> Proxy["Deploy Proxy"]
    Proxy --> App["Deploy Django App"]
    App --> PG["PostgreSQL"]
    App --> Redis["Redis"]
    Redis --> Worker["Celery Worker"]

Deployment Runbook Core¶

# start stack
docker compose -f docker-compose-deploy.yml up -d --build

# schema/static checks
docker compose -f docker-compose-deploy.yml run --rm <deploy-app-service> python manage.py migrate
docker compose -f docker-compose-deploy.yml run --rm <deploy-app-service> python manage.py collectstatic --noinput
docker compose -f docker-compose-deploy.yml run --rm <deploy-app-service> python manage.py check

10. Security Architecture¶

Security posture is enforced by settings + middleware + controlled account behavior.

Key controls include:

• secure defaults outside debug mode
• CSP and permissions-policy headers
• CSRF trusted origin enforcement
• login-required and MFA-required middleware
• auth endpoint rate-limit controls

flowchart LR
    Req["Incoming Request"] --> Sec["Security Middleware"]
    Sec --> Auth["Auth + MFA Controls"]
    Auth --> Policy["Policy Headers"]
    Policy --> Domain["Domain Processing"]

11. Failure Domains and Diagnostics¶

flowchart TD
    Error["Observed Failure"] --> Type{"Failure Domain"}
    Type -->|Ingress| Proxy["Proxy/Networking"]
    Type -->|Request| App["Django App Logic"]
    Type -->|Persistence| DB["Database/Migrations"]
    Type -->|Async| Async["Redis/Celery"]

First-Response Diagnostics¶

# service state and logs
docker compose ps
docker compose logs -f app celery db redis

# app checks
docker compose run --rm app python manage.py check
docker compose run --rm app python manage.py showmigrations

12. Architectural Rules for Contributors¶

1. Preserve domain boundaries and route ownership.
2. Avoid direct peer-module internal imports.
3. Keep cross-module behavior explicit in shared services/contracts.
4. Add tests for cross-module handoff behavior, not just local module behavior.
5. Validate both request-path and async-path implications for high-impact changes.

Related Pages¶

• Platform Overview
• Domain Applications
• Runtime Modes
• Request Lifecycle
• Data and State Model
• Module Boundaries and Integration Rules
• Module Capability Matrix

Quick Links¶

• Request Lifecycle
• Authentication and Authorization Architecture
• Module Boundaries and Integration Rules
• Architecture Decision Records