# finnovusconsulting/test architecture

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

- Interactive diagram: https://gitdiagram.com/finnovusconsulting/test
- Repository: https://github.com/finnovusconsulting/test

## Overview

##### Project Type and Purpose
- This is a full-stack, enterprise-grade AI platform (“Finnovus AI”) providing financial insights via a multi-agent system (the “Finnovus Five”), plus BI modules (reporting, payroll, file collaboration), multilingual voice, credit/billing, RBAC security, and JSON export APIs.

##### File Structure (inferred from README)
- Top-level service folders for each AI agent: `/ace-advisory`, `/hannan-tax`, `/lex-compliance`, `/predictive-evaluation` (NOVA Forecasting).
- Business modules: `/reports`, `/file-collaboration`, `/payroll`, `/billing`, `/credit-cockpit`.
- Shared/backend code under `server/`: engines (`ace-engine.ts`, `hannan-tax-engine.ts`, `lex-compliance-engine.ts`, `voice-engine.ts`), routes (`routes.ts`), billing/payment (`payment-manager.ts`), storage layer, enhanced payroll/reporting services.
- Shared schema definitions: `shared/schema.ts`.
- Frontend code under `client/`: pages in `client/src/pages/*.tsx`, Vite, Tailwind, shadcn/ui, Wouter routing, TanStack Query.
- Config files: `package.json`, `drizzle.config.ts`, environment variables, Replit deployment.

##### README for Architectural Insights
- Frontend: React+TypeScript SPA served by Vite Dev Server/static hosting.
- Backend: Node.js + Express.js monolith (modularized into sub-services) with Passport.js sessions.
- Database: PostgreSQL accessed via Drizzle ORM.
- External Integrations: OpenAI GPT-4, Stripe, SendGrid, Make.com webhooks.
- Security: RBAC, rate limiting, input sanitization, audit logging.

##### Main Components & Relationships
a. Frontend (Browser SPA)
- Pages/components call backend JSON APIs over HTTPS.
- State management with TanStack Query; routing with Wouter.
b. API Gateway (Express.js)
- Central `server/routes.ts` routes to sub-modules.
- Middlewares: authentication/session, RBAC, rate limiter, input sanitizer, audit logger.
c. Business Logic Modules (Node services)
- AI Engines: ACE, Hannan Tax, LEX Compliance, NOVA Forecasting, Voice Engine.
- BI Modules: Reporting, File Collaboration, Enhanced Payroll, Credit & Billing.
- Each module exports its own route handlers and credits-billing logic.
d. Data Layer
- PostgreSQL database (schema in `shared/schema.ts`).
- Drizzle ORM for queries and migrations.
- Storage layer for file uploads (Excel, CSV, docs).
e. External Services
- OpenAI API for LLM calls (GPT-4).
- Stripe for payments.
- SendGrid for emails.
- Make.com via JSON-export webhooks.
f. Infrastructure & Deployment
- Replit auto-scaling with health checks and TLS.

##### Architectural Patterns & Design Principles
- Modular Monolith: logically separated modules within one Express app.
- Credit-based billing interceptor on each service.
- Shared middleware for security, logging, sessions.
- Multi-agent design: each AI engine is a separate component interacting via unified API.
- Clear separation of concerns: UI vs. API vs. data vs. external integrations.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top Layer: Frontend
    Frontend["React+TypeScript SPA\n(Vite, Tailwind, shadcn/ui)"]:::ui

    %% Backend Container
    subgraph "Backend" 
        direction TB
        APIGateway["API Gateway\nExpress.js"]:::backend

        subgraph "Shared Middleware"
            direction TB
            Auth["Authentication & RBAC"]:::middleware
            RateLimit["Rate Limiter"]:::middleware
            Sanitizer["Input Sanitization"]:::middleware
            AuditLog["Audit Logger"]:::middleware
        end

        subgraph "Finnovus Five (AI Engines)"
            direction TB
            ACE["ACE Advisory Engine"]:::service
            HANNAN["Hannan Tax Engine"]:::service
            LEX["LEX Compliance Engine"]:::service
            NOVA["NOVA Forecasting Engine"]:::service
            VOICE["Voice Engine"]:::service
        end

        subgraph "BI Modules"
            direction TB
            REPORTS["Reporting Module"]:::service
            PAYROLL["Enhanced Payroll Module"]:::service
            FILECOLLAB["File Collaboration Module"]:::service
            BILLING["Billing & Credit Cockpit"]:::service
        end
    end

    %% Data Layer
    DB[(PostgreSQL Database)]:::data
    Storage["File Storage\n(Excel, CSV, Docs)"]:::data

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI GPT-4"]:::external
        Stripe["Stripe Payments"]:::external
        SendGrid["SendGrid Email"]:::external
        MakeWEB["Make.com Webhooks"]:::external
    end

    %% Connections: Frontend to Backend
    Frontend -->|"HTTPS/JSON"| APIGateway
    Frontend -->|"Voice Commands"| VOICE

    %% API Gateway to Middleware
    APIGateway --> Auth
    Auth --> RateLimit
    RateLimit --> Sanitizer
    Sanitizer --> AuditLog

    %% Middleware to Services
    AuditLog --> ACE
    AuditLog --> HANNAN
    AuditLog --> LEX
    AuditLog --> NOVA
    AuditLog --> VOICE
    AuditLog --> REPORTS
    AuditLog --> PAYROLL
    AuditLog --> FILECOLLAB
    AuditLog --> BILLING

    %% Services to Data Layer
    ACE -->|"ORM Query"| DB
    HANNAN -->|"ORM Query"| DB
    LEX -->|"ORM Query"| DB
    NOVA -->|"ORM Query"| DB
    VOICE -->|"ORM Query"| DB
    REPORTS -->|"ORM Query"| DB
    PAYROLL -->|"ORM Query"| DB
    FILECOLLAB -->|"ORM Query"| DB
    BILLING -->|"ORM Query"| DB

    FILECOLLAB -->|"Store Files"| Storage

    %% Services to External Services
    ACE -->|"LLM Calls"| OpenAI
    HANNAN -->|"LLM Calls"| OpenAI
    LEX -->|"LLM Calls"| OpenAI
    NOVA -->|"LLM Calls"| OpenAI
    VOICE -->|"Speech API"| OpenAI

    BILLING -->|"Payments API"| Stripe
    BILLING -->|"Email Receipts"| SendGrid

    REPORTS -->|"Webhook"| MakeWEB

    %% Styles
    classDef ui fill:#D0E7FF,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#DFF7E0,stroke:#2E8B57,color:#2E8B57;
    classDef middleware fill:#E8F4FD,stroke:#4682B4,color:#4682B4,stroke-dasharray: 5 5;
    classDef service fill:#E0FFE0,stroke:#228B22,color:#228B22;
    classDef data fill:#FFEBC0,stroke:#DAA520,color:#DAA520;
    classDef external fill:#F0F0F0,stroke:#696969,color:#696969;
```
