# avinash11-ak11/flowbit architecture

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

- Interactive diagram: https://gitdiagram.com/avinash11-ak11/flowbit
- Repository: https://github.com/avinash11-ak11/flowbit

## Overview

##### Project Type and Purpose
- This is a full-stack, multi-tenant workflow management system with a React shell, a React micro-frontend (Support Tickets), a Node.js/Express API, MongoDB, and an n8n workflow engine.
- Core concerns: tenant isolation, real-time updates, dynamic micro-frontend loading, workflow automation.

##### File Structure
- Top-level folders:
- api/                 → Backend API server
- api/src/models/    → MongoDB schemas (AuditLog.js, Ticket.js, User.js)
- api/src/routes/    → REST endpoints (auth.js, users.js, tickets.js, audit.js, webhooks.js)
- api/src/middleware/→ Auth + tenant isolation (auth.js, tenantIsolation.js, errorHandler.js)
- api/src/server.js  → Entry point
- api/database/seed.js & api/src/tests/ → Database seed, unit tests
- shell/               → Main React “Shell” application
- shell/src/pages/           → DashboardPage.jsx, LoginPage.jsx, SupportTicketsPage.jsx
- shell/src/components/      → Header.jsx, Sidebar.jsx, Layout.jsx, LoadingSpinner.jsx
- shell/src/contexts/        → AuthContext.jsx, SocketContext.jsx
- shell/index.html, Dockerfile, vite.config.js, postcss.config.js, tailwind.config.js
- support-tickets-app/ → Micro-frontend for tickets
- support-tickets-app/src/components/ → CreateTicketModal.jsx, TicketDetailModal.jsx
- support-tickets-app/src/SupportTicketsApp.jsx, main.jsx, index.css
- support-tickets-app/index.html, Dockerfile, vite.config.js, postcss.config.js, tailwind.config.js
- database/            → MongoDB init & seed scripts (init.js, seed.js)
- .bolt/, ngrok.yml    → Misc configs
- docker-compose.yml   → Orchestrates shell, api, support-tickets-app, MongoDB, n8n, ngrok
- Root files: package.json, tsconfig.*, index.html (fallback), eslint.config.js.

##### Extract Architectural Insights from README
- Micro-frontend via Webpack Module Federation: shell dynamically loads support-tickets-app at runtime (port 3002).
- API enforces tenant isolation in middleware and uses Socket.io for real-time updates.
- n8n provides webhook-based workflow automation.
- MongoDB holds tenant-scoped collections; `customerId` used everywhere.

##### Main Components & File-Path Mapping
A. React Shell (Port 3000)
- Files: shell/src/main.jsx, shell/src/App.jsx, shell/src/pages/*, shell/src/components/*
- Responsibilities: Authentication flow, screen registry (api/src/config/registry.json), dynamic MF loading.
B. Support Tickets Micro-Frontend (Port 3002)
- Files: support-tickets-app/src/SupportTicketsApp.jsx, support-tickets-app/src/components/*
- Responsibilities: Ticket creation, detail modals, presentation only.
C. API Server (Port 3001)
- Files: api/src/server.js, api/src/routes/*.js, api/src/models/*.js, api/src/middleware/*.js
- Responsibilities: Auth (JWT), RBAC, tenant filtering, REST endpoints, webhooks, Socket.io.
D. Database (MongoDB, Port 27017)
- Files: database/init.js, database/seed.js, api/database/seed.js
- Collections: tickets, users, auditLogs, each with `customerId`.
E. Workflow Engine (n8n, Port 5678)
- External service receiving webhooks at /webhook/flowbit-ticket → processes → calls /webhook/ticket-done.
- Config: ngrok.yml for tunneling if needed.

##### Relationships and Data Flows
- User → React Shell (3000) → API (3001) → MongoDB (27017)
- React Shell ↔ Socket.io on API for real-time events
- Shell dynamically imports Support Tickets from support-tickets-app (3002)
- API → n8n webhook (5678) → n8n workflow → API callback
- Database seed scripts run via docker-compose or `npm run seed`

##### Architectural Patterns & Principles
- Micro-frontend architecture (Module Federation)
- MVC-style API (models, routes, middleware)
- Tenant isolation enforced at middleware and query levels
- Event-driven workflows with webhooks + Socket.io for live updates
- Containerization with Docker Compose for dev/production parity

##### Including Full File Paths
– api/src/server.js
– api/src/middleware/auth.js, tenantIsolation.js
– api/src/routes/*.js
– api/src/models/*.js
– shell/src/main.jsx, App.jsx
– shell/src/pages/*.jsx
– shell/src/components/*.jsx
– shell/src/contexts/*.jsx
– support-tickets-app/src/SupportTicketsApp.jsx
– support-tickets-app/src/components/*.jsx
– database/init.js, database/seed.js
– api/database/seed.js
- n8n: note external, no code files in repo but reference port and workflow URL.

##### Final Checklist
- Clear component labels, including port numbers

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Browser
    User["User Browser"]:::external

    %% Frontend Layer: React Shell
    subgraph "React Shell (3000)" 
        direction TB
        Shell["Files:\n- shell/src/main.jsx\n- shell/src/App.jsx\n- shell/src/pages/DashboardPage.jsx, LoginPage.jsx, SupportTicketsPage.jsx\n- shell/src/components/Header.jsx, Sidebar.jsx, Layout.jsx, LoadingSpinner.jsx\n- shell/src/contexts/AuthContext.jsx, SocketContext.jsx\n- shell/index.html, vite.config.js, postcss.config.js, tailwind.config.js, Dockerfile"]:::frontend
    end

    %% Frontend Layer: Support Tickets Micro-Frontend
    subgraph "Support Tickets MF (3002)"
        direction TB
        TicketsApp["Files:\n- support-tickets-app/src/main.jsx\n- support-tickets-app/src/SupportTicketsApp.jsx\n- support-tickets-app/src/components/CreateTicketModal.jsx, TicketDetailModal.jsx\n- support-tickets-app/index.html, vite.config.js, postcss.config.js, tailwind.config.js, Dockerfile"]:::frontend
    end

    %% Backend API Server
    subgraph "API Server (3001)"
        direction TB
        APIServer["Files:\n- api/src/server.js\n- api/src/routes/auth.js, users.js, tickets.js, audit.js, webhooks.js\n- api/src/models/User.js, Ticket.js, AuditLog.js\n- api/src/middleware/auth.js, tenantIsolation.js, errorHandler.js\n- api/src/config/registry.json\n- api/database/seed.js\n- api/Dockerfile, package.json"]:::backend
    end

    %% Database
    subgraph "MongoDB (27017)"
        direction TB
        DB["Files:\n- database/init.js\n- database/seed.js\n- api/database/seed.js"]:::db
    end

    %% Workflow Engine
    n8n["n8n Workflow Engine (5678)\nExternal Service\nWebhooks:\n- /webhook/flowbit-ticket\n- /webhook/ticket-done"]:::external

    %% Connections
    User -->|"HTTP"| Shell
    Shell -->|"Module Federation (HTTP)"| TicketsApp
    Shell -->|"HTTP REST / WebSocket"| APIServer
    Shell ---|"Socket.io"| APIServer
    APIServer -->|"MongoDB Driver"| DB
    APIServer -->|"Webhook (HTTP)"| n8n
    n8n -->|"Webhook Callback"| APIServer

    %% Click Events
    click Shell "https://github.com/avinash11-ak11/flowbit/tree/main/shell"
    click TicketsApp "https://github.com/avinash11-ak11/flowbit/tree/main/support-tickets-app"
    click APIServer "https://github.com/avinash11-ak11/flowbit/tree/main/api"
    click DB "https://github.com/avinash11-ak11/flowbit/tree/main/database"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#4D90FE,color:#000;
    classDef backend fill:#E0F8D0,stroke:#4CAF50,color:#000;
    classDef db fill:#FFF3C4,stroke:#F7C600,color:#000,shape:cylinder;
    classDef external fill:#FFE0B2,stroke:#FB8C00,color:#000;
```
