# sujithr07/ai-driven-firewall architecture

> Architecture diagram of the GitHub repository sujithr07/ai-driven-firewall, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sujithr07/ai-driven-firewall
- Repository: https://github.com/sujithr07/ai-driven-firewall

## Overview

##### Project type & purpose (inferred from tree)
This looks like a **hybrid local “full‑stack” app**:

- **Frontend:** React + Vite (`App.jsx`, `main.jsx`, `index.html`, `vite.config.js`, `tailwind.config.js`, `index.css`, `package.json`).
- **Backend / local agent:** Python entrypoints (`app.py`, `app.pyw`) suggesting a **local service/daemon or desktop-ish launcher** (the `.pyw` is common on Windows to run without a console).
- **Data store:** A local SQLite database (`firewall.db`).
- **Cloud backend (optional/secondary):** Supabase indicated by `SUPABASE_SETUP.md` + `supabase_migration.sql` + `.env`. That implies **remote Postgres schema + auth/log sync**.
- **Domain:** UI screens include `NetworkTrafficView.jsx`, `ImmutableLogsView.jsx`, `SettingsView.jsx`, `Login.jsx` — so likely a **network monitoring/firewall + immutable audit log viewer** with user login and configurable settings.

##### React UI (Vite + Tailwind)
- Key UI modules (components/pages):
`Login`, `NetworkTrafficView`, `ImmutableLogsView`, `SettingsView`, `App`
##### Python Local Service (app.py/app.pyw)
- Likely responsibilities (confirm in code):
- Network traffic / events
- enforce firewall rules / interact with OS/network stack
- provide local HTTP API to UI
- persist local logs/settings
##### Local SQLite DB (`firewall.db`)
- Stores: events/logs, settings, maybe local user/session cache
##### Supabase (external)
- **Auth** (login/session management)
- **Postgres** (schema from `supabase_migration.sql`)
##### Operating System / Network stack (external system)
- Because “network traffic” and “firewall” imply OS-level integration, represent it explicitly as an external dependency the Python service talks to.

Optional/conditional containers to include only if they exist after inspection:
- **Dev server / build pipeline**: Vite dev server in development, static build output in production.
- **Packaging/distribution**: If `app.pyw` is used with something like PyInstaller, show a “Packaged Desktop App” boundary.

##### User → React UI
- Interaction: view traffic, view immutable logs, configure rules/settings

##### React UI → Python Local Service
- Protocol: likely HTTP (REST) or WebSocket (if streaming traffic)
- Data: traffic events, log queries, settings updates, firewall rule changes

##### Python Local Service → OS / Network stack
- “Capture traffic”, “apply firewall rules”, “read interface stats”
- This is crucial: it explains why Python exists vs a purely cloud web app.

##### Python Local Service → Local SQLite (`firewall.db`)
- Write: captured events/logs, immutable log entries, settings
- Read: historical logs, saved configuration

##### Dev/build flows (separate from runtime)
- Dev: React runs via **Vite dev server** and calls Python service on localhost (CORS, proxy config in `vite.config.js`).
- Prod: React is built to static assets and either:
- served by Python (Flask/FastAPI static files), or

##### Local-first architecture
- Local Python service + local SQLite are first-class components.
- Supabase is “cloud augmentation” (auth/sync/reporting) rather than the only backend.

##### Separation of concerns
- React = presentation + interaction
- Python = privileged operations (network/firewall) + persistence + API

##### Immutable/audit logging
- If “ImmutableLogsView” is truly immutable, annotate the data store interactions:
- “append-only”
- “no UPDATE/DELETE” policy (or RLS policies in Supabase)

##### Streaming vs request/response

- Purpose: communicate what this system is and what it integrates with.

- React component view:
- `App.jsx` as shell/router
- `Login`, `NetworkTrafficView`, `ImmutableLogsView`, `SettingsView`
- Python component view (requires opening `app.py`):
- API routes/controllers
- traffic capture module
- firewall/rules module
- persistence layer (SQLite access)
- supabase client/sync job

##### Annotate environments
- “Localhost” boundary: UI + Python + SQLite
- “Cloud” boundary: Supabase
- “OS privileged boundary”: network stack access

- `SUPABASE_SETUP.md` + `supabase_migration.sql`: show **schema/migration path** into Supabase (and note whether it’s used for logs, users, settings, or all).
- `.env`: show configuration inputs for Supabase URL/keys, local ports, etc.
- `requirements.txt`: determines Python framework + libs (pcap? scapy? fastapi? flask?). Add those technology labels once confirmed.
- `vite.config.js`: likely contains proxy settings; mention “UI proxies /api to localhost:<python-port>” if present.
- `app.pyw`: highlight a “desktop launcher” or “runs in background” execution mode if used.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Context / Actors
    %% =========================
    User["User"]:::actor

    %% =========================
    %% Localhost Boundary (Runtime)
    %% =========================
    subgraph "Local Machine (localhost)"
        direction TB

        subgraph "Frontend: React UI (Vite + Tailwind)"
            direction TB
            UI["React Single Page App"]:::frontend

            subgraph "UI Screens / Components"
                direction TB
                AppShell["App Shell / Router"]:::frontend
                Login["Login"]:::frontend
                Traffic["Network Traffic View"]:::frontend
                Immutable["Immutable Logs View"]:::frontend
                Settings["Settings View"]:::frontend
            end
        end

        subgraph "Backend: Python Local Service (Agent/Daemon)"
            direction TB
            PySvc["Python Local Service"]:::backend
            API["Local HTTP API (/api/*)"]:::api
            Stream["Traffic Stream (WebSocket/SSE?)"]:::api
        end

        SQLite[("SQLite: firewall.db")]:::db
    end

    %% =========================
    %% External Systems
    %% =========================
    subgraph "Cloud"
        direction TB
        SupaAuth["Supabase Auth"]:::external
        SupaDB[("Supabase Postgres")]:::db
    end

    OS["OS / Network Stack"]:::external

    %% =========================
    %% Runtime Relationships
    %% =========================
    User -->|"uses"| UI

    UI -->|"renders/route-to"| AppShell
    AppShell -->|"navigates"| Login
    AppShell -->|"navigates"| Traffic
    AppShell -->|"navigates"| Immutable
    AppShell -->|"navigates"| Settings

    UI -->|"REST_JSON"| API
    UI -->|"streaming_events"| Stream

    PySvc -->|"hosts"| API
    PySvc -->|"hosts"| Stream

    PySvc -->|"capture_traffic/apply_rules"| OS
    PySvc -->|"SQL_read/write_logs_settings"| SQLite

    %% =========================
    %% Supabase Integration (two plausible patterns)
    %% =========================
    %% Pattern A: UI auth -> Python (token) -> Supabase DB sync
    UI -.->|"auth_JWT_(PatternA)"| SupaAuth
    UI -.->|"pass_JWT_(PatternA)"| PySvc
    PySvc -.->|"sync_immutable_logs_append_only_(PatternA)"| SupaDB

    %% Pattern B: SPA talks to Supabase directly (peer backend)
    UI -.->|"auth_JWT_(PatternB)"| SupaAuth
    UI -.->|"read/write_(PatternB)"| SupaDB

    %% =========================
    %% Dev / Build / Config Artifacts (non-runtime)
    %% =========================
    subgraph "Repo Configuration & Tooling (dev/build-time)"
        direction TB
        Env["Environment Config (.env)"]:::config
        ViteCfg["Vite Config"]:::config
        TailwindCfg["Tailwind Config"]:::config
        Pkg["Node Package Manifest"]:::config
        PkgLock["Node Package Lock"]:::config
        IndexHtml["index.html"]:::config
        IndexCss["index.css"]:::config
        MainJsx["main.jsx"]:::config

        Req["Python Requirements"]:::config
        PyEntry["Python Entrypoint (app.py)"]:::config
        PywEntry["Windows Launcher (app.pyw)"]:::config

        SupaSetup["Supabase Setup Doc"]:::doc
        SupaMig["Supabase Migration (SQL)"]:::config
    end

    Env -.->|"configures"| UI
    Env -.->|"configures"| PySvc
    ViteCfg -.->|"proxy_/api_to_local_python"| UI
    TailwindCfg -.->|"styles_build"| UI
    Pkg -.->|"build_scripts"| UI
    PkgLock -.->|"dependency_lock"| UI
    IndexHtml -.->|"spa_shell"| UI
    IndexCss -.->|"global_styles"| UI
    MainJsx -.->|"bootstraps"| UI

    Req -.->|"pins_deps"| PySvc
    PyEntry -.->|"runs_service"| PySvc
    PywEntry -.->|"runs_background"| PySvc

    SupaSetup -.->|"guides_setup"| SupaAuth
    SupaSetup -.->|"guides_setup"| SupaDB
    SupaMig -.->|"applies_schema"| SupaDB

    %% =========================
    %% Notes / Annotations
    %% =========================
    Note1["Immutable Logs: prefer append-only writes; avoid UPDATE/DELETE (enforce via DB constraints/RLS if used)"]:::note
    Immutable -.->|"views"| Note1
    PySvc -.->|"writes"| Note1
    SupaDB -.->|"stores"| Note1
    SQLite -.->|"stores"| Note1

    %% =========================
    %% Click Events (from component_mapping)
    %% =========================
    click AppShell "https://github.com/sujithr07/ai-driven-firewall/blob/main/App.jsx"
    click MainJsx "https://github.com/sujithr07/ai-driven-firewall/blob/main/main.jsx"
    click IndexHtml "https://github.com/sujithr07/ai-driven-firewall/blob/main/index.html"
    click IndexCss "https://github.com/sujithr07/ai-driven-firewall/blob/main/index.css"
    click ViteCfg "https://github.com/sujithr07/ai-driven-firewall/blob/main/vite.config.js"
    click TailwindCfg "https://github.com/sujithr07/ai-driven-firewall/blob/main/tailwind.config.js"
    click Pkg "https://github.com/sujithr07/ai-driven-firewall/blob/main/package.json"
    click PkgLock "https://github.com/sujithr07/ai-driven-firewall/blob/main/package-lock.json"

    click Login "https://github.com/sujithr07/ai-driven-firewall/blob/main/Login.jsx"
    click Traffic "https://github.com/sujithr07/ai-driven-firewall/blob/main/NetworkTrafficView.jsx"
    click Immutable "https://github.com/sujithr07/ai-driven-firewall/blob/main/ImmutableLogsView.jsx"
    click Settings "https://github.com/sujithr07/ai-driven-firewall/blob/main/SettingsView.jsx"

    click PyEntry "https://github.com/sujithr07/ai-driven-firewall/blob/main/app.py"
    click PywEntry "https://github.com/sujithr07/ai-driven-firewall/blob/main/app.pyw"
    click Req "https://github.com/sujithr07/ai-driven-firewall/blob/main/requirements.txt"

    click SQLite "https://github.com/sujithr07/ai-driven-firewall/blob/main/firewall.db"

    click SupaSetup "https://github.com/sujithr07/ai-driven-firewall/blob/main/SUPABASE_SETUP.md"
    click SupaMig "https://github.com/sujithr07/ai-driven-firewall/blob/main/supabase_migration.sql"
    click Env "https://github.com/sujithr07/ai-driven-firewall/blob/main/.env"

    %% =========================
    %% Styling
    %% =========================
    classDef actor fill:#ffffff,stroke:#334155,stroke-width:2,color:#0f172a
    classDef frontend fill:#dbeafe,stroke:#1d4ed8,stroke-width:2,color:#0f172a
    classDef backend fill:#bfdbfe,stroke:#1e40af,stroke-width:2,color:#0f172a
    classDef api fill:#93c5fd,stroke:#1e3a8a,stroke-width:2,color:#0f172a
    classDef db fill:#e5e7eb,stroke:#374151,stroke-width:2,color:#111827
    classDef external fill:#ffedd5,stroke:#c2410c,stroke-width:2,color:#7c2d12
    classDef config fill:#dcfce7,stroke:#166534,stroke-width:2,color:#052e16
    classDef doc fill:#fef9c3,stroke:#a16207,stroke-width:2,color:#713f12
    classDef note fill:#fce7f3,stroke:#9d174d,stroke-width:2,color:#831843
```
