# savantly-net/nexus-command architecture

> Architecture diagram of the GitHub repository savantly-net/nexus-command, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/savantly-net/nexus-command
- Repository: https://github.com/savantly-net/nexus-command

## Overview

##### Main Components
- Web User Interface – the default webapp that contains the front-end logic, static resources (CSS, JavaScript, HTML templates), and is responsible for interacting with the user.
- Application Server / Business Logic – the core of the application is built as an Apache Causeway application and is broken into multiple Maven modules (for example: module-organizations, module-projects, module-franchise, module-security, module-web, module-ai, etc.). Each module encapsulates a specific business domain or functionality.
- Persistence / Database Layer – the application uses an in-memory H2 database by default with support (via Flyway migrations) for production databases like Postgres or SQL Server.
- Infrastructure & DevOps – Docker Compose files, Kubernetes/Docker deployment files (the Docker, Procfile, and multiple docker-compose files) illustrate that containerized deployment is supported.

##### Breakdown of Architectural Layers and Zones
- Presentation / Client Layer:
- Webapp front-end (located in the “webapp” directory).
- Static assets (CSS, images, templates) and the configuration of the Apache Causeway-based UI.
- Business Logic / Application Modules:
- That these modules are enabled/disabled by configuration properties (see README’s “Common Configurations” section).
- Role of Apache Causeway as the framework that unifies domain-driven design (with attached domain classes, fixtures, and integration tests for rapid model-driven development).
- Persistence Layer:
- A database component that may represent H2 or relational databases managed via Flyway.
- A note that load-time weaving and JPA (via EclipseLink) are used.
- Integration Layer:
- Messaging components (Kafka module, webhooks module) and external REST/API integrations.
- Platform Operations:
- Container management (Docker files, Makefile commands, deployment scripts) and Continuous Integration aspects (GitHub workflows, Maven wrapper scripts).

##### Relationships and Interactions
- Interactions between business modules (e.g., organization management, project management, franchise management) – even if these are tightly coupled as modules within a monolithic architecture, show them as logical components connecting through a common service layer.
- Database transactions coming from business modules and DAOs/repositories.
- Integration paths from business modules to external systems like messaging (Kafka, webhooks) and authentication (OAuth2).

##### Highlighting Architectural Patterns
- Layered or MVC-like Pattern – separate UI, business logic, and persistence.
- Plugin/Extensibility – explain that the modules are designed to be used either within the default webapp or in a custom composable application.
- Integration Patterns – asynchronous messaging, API gateways, and external service hooks.

##### Relevant Technologies
- Apache Causeway (as the framework for rapid domain-driven application development)
- Java 17, Maven – indicating the build and language stack.
- Docker, Docker Compose – for containerizing the application.
- EclipseLink JPA with load-time weaving (spring-instrument)
- Messaging Systems: Kafka (module-kafka) and webhooks (module-webhooks)
- Databases: H2 (default), PostgreSQL/SQL Server (configurable via profiles)

## Diagram (Mermaid)

```mermaid
flowchart TD 
    subgraph "Presentation Layer"
        UI["Web Frontend (Default Webapp)"]:::frontend
    end

    subgraph "Business Logic Layer"
        BC["Apache Causeway Framework"]:::business
        MO["Organizations Module"]:::business
        MP["Projects Module"]:::business
        MF["Franchise Module"]:::business
        MS["Security Module"]:::business
        MW["Default Web Module"]:::business
        MA["AI Module"]:::business
        OM["Other Modules"]:::business
    end

    subgraph "Persistence Layer"
        DB["H2/Relational Database (Persistence)"]:::db
        FM["Flyway Migrations"]:::db
        SI["Spring Instrumentation (Load-time Weaving)"]:::db
    end

    subgraph "Integration Layer"
        KAFKA["Kafka Integration"]:::integration
        WEBHOOKS["Webhooks Integration"]:::integration
        GA_FLOW["Google Analytics Flow"]:::integration
        GA["Google Analytics"]:::integration
    end

    subgraph "Infrastructure & DevOps"
        DEPLOY["Docker & Deployment (Docker, Compose, Procfile, Makefile)"]:::devops
    end

    %% Relationships
    UI -->|"triggers"| BC
    BC -->|"invokes"| MO
    BC -->|"invokes"| MP
    BC -->|"invokes"| MF
    BC -->|"invokes"| MS
    BC -->|"invokes"| MW
    BC -->|"invokes"| MA
    BC -->|"invokes"| OM
    UI <-->|"receives"| BC

    BC -->|"persists"| DB
    MO -->|"writes to"| DB
    MP -->|"writes to"| DB
    MF -->|"writes to"| DB
    MS -->|"writes to"| DB
    MW -->|"writes to"| DB
    MA -->|"writes to"| DB
    OM -->|"writes to"| DB

    BC -->|"emits"| KAFKA
    BC -->|"emits"| WEBHOOKS
    BC -->|"emits"| GA_FLOW
    BC -->|"emits"| GA

    SI -->|"weaves"| DB
    FM -->|"updates"| DB

    DEPLOY -->|"deploys"| UI
    DEPLOY -->|"deploys"| BC
    DEPLOY -->|"deploys"| DB
    DEPLOY -->|"deploys"| KAFKA
    DEPLOY -->|"deploys"| WEBHOOKS
    DEPLOY -->|"deploys"| GA_FLOW
    DEPLOY -->|"deploys"| GA

    %% Click Events
    click UI "https://github.com/savantly-net/nexus-command/tree/main/webapp"
    click MO "https://github.com/savantly-net/nexus-command/tree/main/module-organizations"
    click MP "https://github.com/savantly-net/nexus-command/tree/main/module-projects"
    click MF "https://github.com/savantly-net/nexus-command/tree/main/module-franchise"
    click MS "https://github.com/savantly-net/nexus-command/tree/main/module-security"
    click MW "https://github.com/savantly-net/nexus-command/tree/main/module-web"
    click MA "https://github.com/savantly-net/nexus-command/tree/main/module-ai"
    click FM "https://github.com/savantly-net/nexus-command/tree/main/webapp/src/main/resources/db/migration"
    click SI "https://github.com/savantly-net/nexus-command/blob/main/lib/spring-instrument.jar"
    click KAFKA "https://github.com/savantly-net/nexus-command/tree/main/module-kafka"
    click WEBHOOKS "https://github.com/savantly-net/nexus-command/tree/main/module-webhooks"
    click GA_FLOW "https://github.com/savantly-net/nexus-command/tree/main/module-google-analytics-flow"
    click GA "https://github.com/savantly-net/nexus-command/tree/main/module-google-analytics"
    click DEPLOY "https://github.com/savantly-net/nexus-command/tree/main/docker"

    %% Styles
    classDef frontend fill:#ffefc6,stroke:#333,stroke-width:2px;
    classDef business fill:#c6e0ff,stroke:#333,stroke-width:2px;
    classDef db fill:#c6ffc6,stroke:#333,stroke-width:2px;
    classDef integration fill:#ffc6f9,stroke:#333,stroke-width:2px;
    classDef devops fill:#f9ffc6,stroke:#333,stroke-width:2px;
```
