# chaychoong/jjx architecture

> Architecture diagram of the GitHub repository chaychoong/jjx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chaychoong/jjx
- Repository: https://github.com/chaychoong/jjx

## Overview

##### Project type and purpose
- Jjx is a full-stack Phoenix (Elixir) web application.
- It serves dynamic pages via controllers and LiveView, manages data via Ecto, sends emails, interacts with a local file system, and includes a native Erlang NIF implemented in Rust.

##### File structure
- Top-level Phoenix conventions:
- assets/ (JavaScript, CSS, vendor) – the frontend static pipeline
- config/ – environment-specific settings
- lib/jjx/ – core application code (business logic, file system, mailer, repo)
- lib/jjx_web/ – web interface (controllers, views, LiveView, router, endpoint)
- priv/ – migration scripts, static assets, gettext
- test/ – unit and integration tests
- Native extension:
- native/jj_nif/ – Rust code compiled as an Erlang NIF, invoked from lib/jj/nif.ex
- Build & orchestration:
- mix.exs – Elixir build/dependency config
- Cargo.toml (root & native/) – Rust build config

##### README for additional insights
- Standard Phoenix startup instructions (mix setup, mix phx.server)
- Deployment guide link indicates a typical Phoenix release pattern

a. Main components
- Client Browser (HTTP & WebSocket)
- Phoenix Endpoint (HTTP server & socket transport)
- jjx_web layer:
- Router → Controllers & LiveViews → Templates/Components
- jjx core application:
- Business Logic modules (e.g., file_system/local, mailer)
- Ecto Repo → Database (PostgreSQL or configured adapter)
- Native NIF module (Rust library invoked via nif.ex)
- External services: SMTP server, third-party API, file storage (if any)
b. Relationships & interactions
- Browser ↔ Phoenix Endpoint: HTTP requests & LiveView WebSocket messages
- Endpoint → Router → Controller/LiveView: request routing
- Controllers/LiveViews → Business Logic & Ecto Repo: data operations
- Business Logic → Native NIF: heavy-compute offload
- Ecto Repo ↔ Database: SQL transactions
- Mailer → SMTP or email service API
- FileSystem modules → Local disk or external storage
c. Architectural patterns & design principles
- MVC (Router → Controllers/Views) augmented by LiveView (real-time at server)
- Supervision Tree: Endpoint, Repo, PubSub, Telemetry, custom supervisors
- Bounded contexts: separation between web interface (jjx_web) and domain logic (jjx)
- NIF for performance-critical modules, isolating unsafe native code
d. Key technologies & frameworks
- Elixir & Phoenix (Endpoint, Router, Controllers, LiveView)
- Ecto (Database interactions, Migrations)
- Rust NIF (native/jj_nif)
- JavaScript/CSS asset pipeline (esbuild or Webpack via assets/)
- Telemetry & Logger for observability

- Client Browser
- Phoenix Endpoint
- Web Layer (Router, Controllers, LiveViews, Templates)
- Domain Layer (Business Logic, FileSystem, Mailer)
- Persistence Layer (Ecto Repo → Database)
- Native Layer (Rust NIF)
- External Services (SMTP, third-party APIs)
- Web layer: light blue rectangles
- Business logic: green rectangles
- Annotations:
- “mix setup → compile assets → compile Elixir & Rust code”
- Supervision tree overview in a sidebar

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Side
    ClientBrowser["Client Browser"]:::client
    Assets["assets/"]:::client
    Static["priv/static"]:::client

    ClientBrowser -->|"serves static assets"| Endpoint
    Assets --> ClientBrowser
    Static --> ClientBrowser

    %% Web Layer
    subgraph "Web Layer"
        direction TB
        Endpoint["Phoenix Endpoint"]:::web
        Router["Router"]:::web
        Controller["Controllers"]:::web
        LiveView["LiveView"]:::web
        Templates["Templates & UI Components"]:::web
    end

    Endpoint -->|"HTTP & WebSocket"| Router
    Router -->|"routes to"| Controller
    Router -->|"routes to"| LiveView
    Controller -->|"renders via"| Templates
    LiveView -->|"renders via"| Templates

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        FileSystem["File System"]:::domain
        Mailer["Mailer"]:::domain
    end

    Controller -->|"calls"| FileSystem
    Controller -->|"calls"| Mailer
    LiveView -->|"calls"| FileSystem
    LiveView -->|"calls"| Mailer

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        Repo["Ecto Repo"]:::persistence
        DB["Database"]:::persistence
    end

    FileSystem -->|"uses"| Repo
    Mailer -->|"logs to"| Repo
    Repo <-->|"SQL transactions"| DB

    %% Native Layer
    Native["Rust NIF"]:::native
    FileSystem -.->|"NIF offload"| Native
    Mailer -.->|"NIF offload"| Native

    %% External Services
    subgraph "External Services"
        direction TB
        SMTP["SMTP Server"]:::external
        ThirdAPI["Third-party API"]:::external
    end

    Mailer -.->|"sends email via"| SMTP
    FileSystem -.->|"external storage API"| ThirdAPI

    %% Configuration & Build
    subgraph "Configuration & Build"
        direction TB
        Config["Configuration Files"]:::config
        Mix["mix.exs & mix.lock"]:::config
        CargoRoot["Cargo.toml (root)"]:::config
        CargoNative["native/jj_nif/Cargo.toml"]:::config
    end

    %% Click Events
    click Assets "https://github.com/chaychoong/jjx/tree/main/assets/"
    click Static "https://github.com/chaychoong/jjx/tree/main/priv/static/"
    click Endpoint "https://github.com/chaychoong/jjx/blob/main/lib/jjx_web/endpoint.ex"
    click Endpoint "https://github.com/chaychoong/jjx/blob/main/lib/jjx_web/telemetry.ex"
    click Router "https://github.com/chaychoong/jjx/blob/main/lib/jjx_web/router.ex"
    click Controller "https://github.com/chaychoong/jjx/blob/main/lib/jjx_web/controllers/error_html.ex"
    click Controller "https://github.com/chaychoong/jjx/blob/main/lib/jjx_web/controllers/error_json.ex"
    click Controller "https://github.com/chaychoong/jjx/blob/main/lib/jjx_web/controllers/page_controller.ex"
    click LiveView "https://github.com/chaychoong/jjx/blob/main/lib/jjx_web/live/home_live.ex"
    click Templates "https://github.com/chaychoong/jjx/blob/main/lib/jjx_web/components/core_components.ex"
    click Templates "https://github.com/chaychoong/jjx/blob/main/lib/jjx_web/components/layouts.ex"
    click Templates "https://github.com/chaychoong/jjx/blob/main/lib/jjx_web/components/layouts/root.html.heex"
    click FileSystem "https://github.com/chaychoong/jjx/blob/main/lib/jjx/file_system/local.ex"
    click Mailer "https://github.com/chaychoong/jjx/blob/main/lib/jjx/mailer.ex"
    click Repo "https://github.com/chaychoong/jjx/blob/main/lib/jjx/repo.ex"
    click DB "https://github.com/chaychoong/jjx/tree/main/priv/repo/migrations/"
    click DB "https://github.com/chaychoong/jjx/blob/main/priv/repo/seeds.exs"
    click Native "https://github.com/chaychoong/jjx/blob/main/lib/jj/nif.ex"
    click Native "https://github.com/chaychoong/jjx/blob/main/native/jj_nif/Cargo.toml"
    click Native "https://github.com/chaychoong/jjx/blob/main/native/jj_nif/src/lib.rs"
    click Config "https://github.com/chaychoong/jjx/blob/main/config/config.exs"
    click Config "https://github.com/chaychoong/jjx/blob/main/config/dev.exs"
    click Config "https://github.com/chaychoong/jjx/blob/main/config/test.exs"
    click Config "https://github.com/chaychoong/jjx/blob/main/config/prod.exs"
    click Config "https://github.com/chaychoong/jjx/blob/main/config/runtime.exs"
    click Mix "https://github.com/chaychoong/jjx/blob/main/mix.exs"
    click Mix "https://github.com/chaychoong/jjx/blob/main/mix.lock"
    click CargoRoot "https://github.com/chaychoong/jjx/blob/main/Cargo.toml"
    click CargoNative "https://github.com/chaychoong/jjx/blob/main/native/jj_nif/Cargo.toml"

    %% Styles
    classDef client fill:#E0F7FA,stroke:#0288D1,color:#000
    classDef web fill:#BBDEFB,stroke:#1976D2,color:#000
    classDef domain fill:#C8E6C9,stroke:#388E3C,color:#000
    classDef persistence fill:#FFE0B2,stroke:#F57C00,color:#000
    classDef native fill:#CFD8DC,stroke:#455A64,color:#000
    classDef external fill:#E1BEE7,stroke:#8E24AA,color:#000
    classDef config fill:#F0F4C3,stroke:#9E9D24,color:#000
```
