# devmhrn/imf_gadgetapi architecture

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

- Interactive diagram: https://gitdiagram.com/devmhrn/imf_gadgetapi
- Repository: https://github.com/devmhrn/imf_gadgetapi

## Overview

##### Project Type & Purpose
- Full-stack web application:
– Backend: Secure REST API managing covert gadgets
– Frontend: Single-Page App for agents/handlers/admins
- Mission: CRUD + emergency self-destruct on gadgets, JWT auth, role-based access.

##### File Structure & Architectural Patterns
- backend/
– app.js: entry point, Express server setup
– config/: DB & environment config
– controllers/: request handlers (auth, gadget) → MVC “C” layer
– models/: Sequelize ORM entities → “M” layer
– routes/: URL → controller bindings
– middlewares/: auth, error handling, rate limiting
– services/: internal logic (codename generator)
– utils/: logging
– DockerFile + docker-compose.yml → containerization
- frontend/
– Vite + React + Tailwind CSS
– src/pages/: routable views (login, dashboard)
– src/components/: UI widgets
– src/libs/apiCalls.js: API wrapper
– src/libs/firebaseConfig.js: integrates Firebase Auth
– src/store/: client-side state management

Pattern:
- Backend follows MVC + Service pattern
- Frontend follows component-based SPA with API layer

##### README for Extra Context
- External services: Firebase Authentication for login
- Database: PostgreSQL (Sequelize ORM)
- Security: AES-256 JWT tokens, bcrypt, role enforcement
- Deployment: Docker + docker-compose

##### Main Components & Their Interactions
A. Components
1. Frontend SPA (React/Vite)
2. Firebase Auth (external service)
3. Backend API (Express/Node)
- Auth Module (login, JWT issuance/validation)
- Gadget Module (controllers, services, routes)
- Database Access (Sequelize)
4. PostgreSQL Database
5. Internal Service: Codename generator
B. Data Flows & Relationships
1. User → Frontend UI (login, gadget management)
2. Frontend → Firebase: obtain firebaseToken
3. Frontend → Backend `/api/auth/login`: send firebaseToken
4. Backend → Firebase: verify token → create internal JWT
5. Frontend attaches JWT to subsequent REST calls (`/api/gadgets`…)
6. Backend → PostgreSQL: read/write gadget & user tables
7. Backend Service: generate random codename and success probability
C. Architectural Patterns
- MVC + Service Layer in backend
- Client-side API wrapper + state store in frontend
- Layered security: Firebase → internal JWT → RBAC
D. Key Technologies
- Node.js, Express, Sequelize, PostgreSQL
- JWT, bcrypt, AES-256 (via jwt library)
- React, Vite, Tailwind CSS
- Firebase Authentication

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation & Client Layer
    FrontendRoot["Frontend SPA"]:::frontend
    click FrontendRoot "https://github.com/devmhrn/imf_gadgetapi/tree/main/frontend/"

    subgraph "Presentation & Client Layer"
        direction TB
        Main["main.jsx"]:::frontend
        click Main "https://github.com/devmhrn/imf_gadgetapi/blob/main/frontend/src/main.jsx"
        App["App.jsx"]:::frontend
        click App "https://github.com/devmhrn/imf_gadgetapi/blob/main/frontend/src/App.jsx"
        LoginPage["login.jsx"]:::frontend
        click LoginPage "https://github.com/devmhrn/imf_gadgetapi/blob/main/frontend/src/pages/login.jsx"
        DashboardPage["Dashboard.jsx"]:::frontend
        click DashboardPage "https://github.com/devmhrn/imf_gadgetapi/blob/main/frontend/src/pages/Dashboard.jsx"
        UIComponents["UI Components"]:::frontend
        click UIComponents "https://github.com/devmhrn/imf_gadgetapi/tree/main/frontend/src/components/"
        APIWrapper["apiCalls.js"]:::frontend
        click APIWrapper "https://github.com/devmhrn/imf_gadgetapi/blob/main/frontend/src/libs/apiCalls.js"
        FirebaseConfig["firebaseConfig.js"]:::frontend
        click FirebaseConfig "https://github.com/devmhrn/imf_gadgetapi/blob/main/frontend/src/libs/firebaseConfig.js"
    end

    %% External Auth Service
    FirebaseAuth["Firebase Authentication"]:::external

    %% Docker Network grouping
    subgraph "Docker Network"
        direction TB
        %% Backend Layer
        subgraph "Backend API" 
            direction TB
            AppJS["app.js"]:::backend
            click AppJS "https://github.com/devmhrn/imf_gadgetapi/blob/main/backend/app.js"
            subgraph Config
                direction TB
                EnvConfig["config.js"]:::backend
                click EnvConfig "https://github.com/devmhrn/imf_gadgetapi/blob/main/backend/config/config.js"
                DBInit["database.init.js"]:::backend
                click DBInit "https://github.com/devmhrn/imf_gadgetapi/blob/main/backend/config/database.init.js"
            end
            subgraph Controllers
                direction TB
                AuthController["auth.controller.js"]:::backend
                click AuthController "https://github.com/devmhrn/imf_gadgetapi/blob/main/backend/controllers/auth.controller.js"
                GadgetController["gadget.controller.js"]:::backend
                click GadgetController "https://github.com/devmhrn/imf_gadgetapi/blob/main/backend/controllers/gadget.controller.js"
            end
            subgraph Routes
                direction TB
                AuthRoute["auth.js (/api/auth)"]:::backend
                click AuthRoute "https://github.com/devmhrn/imf_gadgetapi/blob/main/backend/routes/auth.js"
                GadgetRoute["gadget.js (/api/gadgets)"]:::backend
                click GadgetRoute "https://github.com/devmhrn/imf_gadgetapi/blob/main/backend/routes/gadget.js"
            end
            subgraph Middlewares
                direction TB
                AuthMiddleware["auth.js"]:::backend
                click AuthMiddleware "https://github.com/devmhrn/imf_gadgetapi/blob/main/backend/middlewares/auth.js"
                ErrorMiddleware["error.js"]:::backend
                click ErrorMiddleware "https://github.com/devmhrn/imf_gadgetapi/blob/main/backend/middlewares/error.js"
                RateLimiter["rateLimiter.js"]:::backend
                click RateLimiter "https://github.com/devmhrn/imf_gadgetapi/blob/main/backend/middlewares/rateLimiter.js"
            end
            subgraph Services
                direction TB
                CodenameService["codenames.js"]:::backend
                click CodenameService "https://github.com/devmhrn/imf_gadgetapi/blob/main/backend/services/codenames.js"
            end
            subgraph Utils
                direction TB
                Logger["logger.js"]:::backend
                click Logger "https://github.com/devmhrn/imf_gadgetapi/blob/main/backend/utils/logger.js"
            end
            subgraph Models
                direction TB
                ModelIndex["index.js"]:::backend
                click ModelIndex "https://github.com/devmhrn/imf_gadgetapi/blob/main/backend/models/index.js"
                GadgetModel["gadget.js"]:::backend
                click GadgetModel "https://github.com/devmhrn/imf_gadgetapi/blob/main/backend/models/gadget.js"
                UserModel["user.js"]:::backend
                click UserModel "https://github.com/devmhrn/imf_gadgetapi/blob/main/backend/models/user.js"
            end
            Dockerfile["Dockerfile"]:::backend
            click Dockerfile "https://github.com/devmhrn/imf_gadgetapi/tree/main/backend/DockerFile"
        end

        %% Database
        Postgres["PostgreSQL Database"]:::db
    end

    Compose["docker-compose.yml"]:::backend
    click Compose "https://github.com/devmhrn/imf_gadgetapi/blob/main/docker-compose.yml"

    %% Interactions
    Main -->|loads| App
    App -->|renders| LoginPage
    App -->|renders| DashboardPage
    LoginPage -->|obtain token| FirebaseAuth
    LoginPage -->|POST /api/auth/login| AuthRoute
    FirebaseAuth -->|verify| AuthController
    AuthRoute -->|invoke| AuthController
    AuthController -->|issue JWT| LoginPage
    DashboardPage -->|GET /api/gadgets| GadgetRoute
    GadgetRoute -->|invoke| GadgetController
    GadgetController -->|uses| CodenameService
    GadgetController -->|reads/writes| ModelIndex
    ModelIndex -->|queries| Postgres

    %% Styles
    classDef frontend fill:#cfe2ff,stroke:#0366d6,color:#000000
    classDef backend fill:#d1e7dd,stroke:#0f5132,color:#000000
    classDef db fill:#fce5cd,stroke:#b35c00,color:#000000
    classDef external fill:#e2d0f7,stroke:#5e32a3,color:#000000
```
