# qeagle/reporter-engine architecture

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

- Interactive diagram: https://gitdiagram.com/qeagle/reporter-engine
- Repository: https://github.com/qeagle/reporter-engine

## Overview

##### Project Type & Purpose
- Full-stack web application: “Reporter Engine” is a real-time test-reporting and analytics platform.
- Frontend: React + TypeScript SPA for dashboards, charts, management UIs.
- Backend: Node.js + Express exposing REST endpoints, WebSocket server for live updates, file-upload, AI integration.
- Data Layer: JSON-based storage + SQLite relational DB, optional cloud blob storage for artifacts.

##### File Structure
- Top-level scripts & config: .env.example, CI/CD workflow, deploy scripts, health-check, ESLint/Tailwind/Vite configs.
- server/
– routes/ → controllers/ → services/ → data/
– middleware/ for auth, RBAC, error handling
– server/index.js & cli.js to launch HTTP + WS server
– data/backup & SQLite files + database schema/seeds in server/database/
- src/ (frontend)
– components/ (UI widgets, charts, modals)
– pages/ (route views: Dashboard, Reports, Analysis, Profile)
– contexts/, hooks/, services/apiService.ts, styling & utils
– main.tsx & App.tsx bootstrapping the SPA via Vite

##### Extract Insights from README
- Architecture overview (Frontend, Backend, Data Layer)
- Real-time updates via WebSocket
- Layered design: RESTful API, modular controllers & services
- Extensibility: AIAnalysisService (Groq/OpenAI), Webhooks, PDF/HTML export, Azure Blob integration

a. Main Components
- Clients (Browser / SPA)
- API Gateway / Backend Server
– HTTP REST endpoints (Auth, Tests, Reports, Analysis, Invitations, Webhooks)
– WebSocket server for live test/step notifications
- Business-Logic Layer (services folder):
AIAnalysisService, ReportService, FileUploadService, PDFService, WebSocketService, etc.
- Data Layer:
– SQLite database (server/data/database.sqlite)
– JSON backup store (server/data/backup)
– File system or Azure Blob for artifacts
- External Services:
– AI providers (Groq APIs, OpenAI)
– SMTP/Email for invitations
– CI/CD pipeline Webhooks

b. Relationships & Data Flows
- Client ↔ Backend via HTTP(S) for CRUD and analytic requests
- Client ↔ Backend via WebSocket for live updates (test steps, status changes)
- Backend → SQLite / JSON store for persistence
- Backend → Azure Blob / File system for binary artifacts
- Backend → AI provider (REST/gRPC) for analysis
- Backend → SMTP server for sending invitation emails
- Backend → External Webhooks (CI/CD integration)

c. Architectural Patterns & Principles
- Layered MVC-style organization (routes → controllers → services → data)
- Event-driven real-time communication (WebSocket)
- Separation of concerns: business logic in services, transport in controllers/routes
- Modular, easily‐replaceable data store (JSON vs. SQL vs. cloud blob)
- Stateless API design with JWT‐based auth and RBAC middleware

d. Key Technologies & Libraries
- Frontend: React, Vite, TypeScript, Tailwind CSS, Chart.js, WebSocket API
- Backend: Node.js, Express, ws/socket.io or built-in WebSocket server, sqlite3, JSON file I/O, Azure Blob SDK, nodemailer
- Security & Ops: JWT, Helmet, CORS, ESLint, CI/CD via GitHub Actions, Dockerfile for containerization

##### Detail & Clarity Guidance
- Critical paths: test start → result reporting → real-time dashboard update.
- CI/CD workflow and deployment scripts on the side.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (React SPA)"
        ReactSPA["React SPA"]:::frontend
        Pages["Pages"]:::frontend
        Components["UI Components"]:::frontend
        APIClient["apiService.ts"]:::frontend
        WSContext["WebSocketContext.tsx"]:::frontend

        ReactSPA --> Pages
        ReactSPA --> Components
        ReactSPA --> APIClient
        ReactSPA --> WSContext
    end

    %% Backend Server
    subgraph "Backend Server (Express)" 
        EntryIndex["server/index.js"]:::backend
        EntryCLI["server/cli.js"]:::backend

        subgraph "API Layer"
            Routes["Routes"]:::backend
            Controllers["Controllers"]:::backend
        end

        subgraph "Services (Business Logic)"
            Services["Services"]:::backend
        end

        Middleware["Middleware"]:::backend

        EntryIndex --> Routes
        EntryCLI --> Routes
        Routes --> Controllers
        Controllers --> Services
        Controllers --> Middleware
    end

    %% Data Layer
    subgraph "Data Layer"
        SQLite["SQLite DB"]:::data
        JSONBackup["JSON Backup Store"]:::data
        BlobStorage["Blob Storage"]:::data
        DatabaseSchema["schema.sql & seeds.sql"]:::data

        SQLite --> DatabaseSchema
    end

    %% External Integrations
    subgraph "External Integrations"
        AIProvider["AI Provider (Groq/OpenAI)"]:::external
        SMTP["SMTP/Email"]:::external
        CIWebhooks["CI/CD Webhooks"]:::external
    end

    %% Connections
    Pages -->|"HTTP(S)"| EntryIndex
    APIClient -->|"HTTP(S)"| EntryIndex
    WSContext -->|"WS"| EntryIndex
    EntryIndex -->|"SQL"| SQLite
    EntryIndex -->|"FS/Azure SDK"| BlobStorage
    EntryIndex -->|"JSON I/O"| JSONBackup
    Services -->|"REST/gRPC"| AIProvider
    Services -->|"SMTP"| SMTP
    Services -->|"POST"| CIWebhooks

    %% Click Events
    click ReactSPA "https://github.com/qeagle/reporter-engine/tree/main/src/"
    click Pages "https://github.com/qeagle/reporter-engine/tree/main/src/pages/"
    click Components "https://github.com/qeagle/reporter-engine/tree/main/src/components/"
    click APIClient "https://github.com/qeagle/reporter-engine/blob/main/src/services/apiService.ts"
    click WSContext "https://github.com/qeagle/reporter-engine/blob/main/src/contexts/WebSocketContext.tsx"
    click EntryIndex "https://github.com/qeagle/reporter-engine/blob/main/server/index.js"
    click EntryCLI "https://github.com/qeagle/reporter-engine/blob/main/server/cli.js"
    click Routes "https://github.com/qeagle/reporter-engine/tree/main/server/routes/"
    click Controllers "https://github.com/qeagle/reporter-engine/tree/main/server/controllers/"
    click Services "https://github.com/qeagle/reporter-engine/tree/main/server/services/"
    click Middleware "https://github.com/qeagle/reporter-engine/tree/main/server/middleware/"
    click SQLite "https://github.com/qeagle/reporter-engine/blob/main/server/data/database.sqlite"
    click JSONBackup "https://github.com/qeagle/reporter-engine/tree/main/server/data/backup/"

    %% Styles
    classDef frontend fill:#cfe2ff,stroke:#2f6fca,color:#000
    classDef backend fill:#d1e7dd,stroke:#238636,color:#000
    classDef data fill:#fde2b7,stroke:#d97706,color:#000
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#000
```
