# hamzabhiinder/openwebuibackend architecture

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

- Interactive diagram: https://gitdiagram.com/hamzabhiinder/openwebuibackend
- Repository: https://github.com/hamzabhiinder/openwebuibackend

## Overview

##### Project Type and Purpose
- This is a monolithic backend API (“OpenWebUI Backend”) built with Node.js, Express, and Prisma.
- It provides authentication, chat management, file processing, AI integration, payment processing, and admin features for a full-stack platform.

##### File-Structure–Based Architectural Insights
- Top-level “src/” contains:
- config/ – DB and Passport setup
- middleware/ – JWT auth, optional auth, file upload, usage tracking
- routes/ – REST endpoints grouped by feature (auth, chats, files, ai, payments, admin, etc.)
- services/ – business logic modules (AI, file processing, usage tracking, helper functions)
- server.js – Express bootstrapping, middleware registration, route mounting
- Prisma schema and migrations under “prisma/” drive a PostgreSQL database.
- A local “uploads/” directory (or S3 in production) stores user-uploaded files.
- External scripts under “scripts/” seed and set up the database.

##### README–Driven Technical Stack
- HTTP API: Express
- Database: PostgreSQL via Prisma ORM
- Auth: JWT, bcrypt, role-based access
- File Processing: multer upload middleware, Tesseract.js OCR, custom fileProcessor service
- AI: OpenAI/Anthropic via ai-service, token tracking via usage-service
- Payments: Stripe, PayPal, MercadoPago SDKs, subscription and webhook handling
- Admin: analytics, user & payment management

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients and Gateway
    Client["Clients\n(Web UI / Mobile App / API)"]:::external
    Gateway["API Gateway\n/ Load Balancer"]:::internal
    Client -->|"HTTP Requests"| Gateway

    %% Server Node
    Server["Express Server\n(Node.js Runtime)"]:::internal
    Gateway --> Server

    %% Server Layers
    subgraph "HTTP Layer"
        direction TB
        AuthRoutes["auth.js\n(Auth Routes)"]:::internal
        ChatsRoutes["chats.js\n(Chat Routes)"]:::internal
        FilesRoutes["files.js\n(File Routes)"]:::internal
        AiRoutes["ai.js\n(AI Routes)"]:::internal
        PaymentsRoutes["payments.js\n(Payment Routes)"]:::internal
        AdminRoutes["admin.js\n(Admin Routes)"]:::internal
        UsersRoutes["users.js\n(User Routes)"]:::internal
        DownloadRoutes["download.js\n(Download Routes)"]:::internal
        ElevenLabsRoutes["elevenlabs.js\n(Voice Routes)"]:::internal
        GptsRoutes["gpts.js\n(GPT Routes)"]:::internal
        LibraryRoutes["library.js\n(Content Library)"]:::internal
        PublicRoutes["public.js\n(Public Routes)"]:::internal
        SearchRoutes["search.js\n(Search Routes)"]:::internal
        VideoRoutes["video.js\n(Video Routes)"]:::internal
    end

    subgraph "Middleware Layer"
        direction TB
        AuthMW["auth.js\n(JWT Auth)"]:::internal
        OptAuthMW["optionalAuth.js\n(Optional Auth)"]:::internal
        UploadMW["upload.js\n(File Upload)"]:::internal
        TrackUsageMW["trackAnonUsage.js\n(Usage Tracking)"]:::internal
    end

    subgraph "Service Layer"
        direction TB
        AiService["ai-service.js\n(AI Integration)"]:::internal
        FileProcessor["fileProcessor.js\n(OCR & File)"]:::internal
        UsageService["usage-service.js\n(Usage Logic)"]:::internal
        HelperSvc["helper.js\n(Helper Functions)"]:::internal
    end

    %% Config Layer
    subgraph "Configuration"
        direction TB
        DBConfig["database.js\n(Prisma Client)"]:::internal
        PassportConfig["passport.js\n(JWT Strategy)"]:::internal
    end

    %% Persistence
    subgraph "Persistence / ORM"
        direction TB
        PrismaSchema["schema.prisma"]:::datastore
        Migrations["migrations/"]:::datastore
        SeedScript["seed.js"]:::datastore
    end

    %% File Storage
    subgraph "File Storage"
        direction TB
        UploadsDir["uploads/"]:::datastore
        TesseractData["eng.traineddata"]:::datastore
    end

    %% External Scripts
    Scripts["scripts/setup-db.js\n(DB Init Script)"]:::internal

    %% External Services
    subgraph "External Integrations"
        direction TB
        AIProviders["OpenAI / Anthropic"]:::external
        OCREngine["Tesseract.js"]:::external
        PaymentGateways["Stripe / PayPal / MercadoPago"]:::external
    end

    %% Flows inside Server
    Server -->|"mounts routes"| AuthRoutes
    Server --> ChatsRoutes
    Server --> FilesRoutes
    Server --> AiRoutes
    Server --> PaymentsRoutes
    Server --> AdminRoutes
    Server --> UsersRoutes
    Server --> DownloadRoutes
    Server --> ElevenLabsRoutes
    Server --> GptsRoutes
    Server --> LibraryRoutes
    Server --> PublicRoutes
    Server --> SearchRoutes
    Server --> VideoRoutes

    AuthRoutes --> AuthMW
    ChatsRoutes --> AuthMW
    FilesRoutes --> UploadMW
    FilesRoutes --> AuthMW
    AdminRoutes --> AuthMW
    PaymentsRoutes --> AuthMW
    AiRoutes --> AuthMW
    PublicRoutes --> OptAuthMW

    AuthMW --> TrackUsageMW
    OptAuthMW --> TrackUsageMW

    TrackUsageMW --> AiService
    TrackUsageMW --> UsageService
    UploadMW --> FileProcessor

    AiService --> AIProviders
    FileProcessor --> OCREngine
    UsageService --> PrismaSchema
    HelperSvc --> PrismaSchema

    %% Persistence flows
    AiService --> PrismaSchema
    FileProcessor --> UploadsDir
    PaymentsRoutes --> PaymentGateways
    UsageService --> Migrations
    Scripts --> PrismaSchema

    %% Config connections
    Server --> DBConfig
    Server --> PassportConfig
    DBConfig --> PrismaSchema

    %% One-time migrations
    Scripts --> Migrations

    %% Click Events
    click Server "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/server.js"
    click DBConfig "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/config/database.js"
    click PassportConfig "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/config/passport.js"
    click AuthMW "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/middleware/auth.js"
    click OptAuthMW "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/middleware/optionalAuth.js"
    click UploadMW "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/middleware/upload.js"
    click TrackUsageMW "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/middleware/trackAnonUsage.js"
    click AuthRoutes "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/routes/auth.js"
    click ChatsRoutes "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/routes/chats.js"
    click FilesRoutes "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/routes/files.js"
    click AiRoutes "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/routes/ai.js"
    click PaymentsRoutes "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/routes/payments.js"
    click AdminRoutes "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/routes/admin.js"
    click UsersRoutes "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/routes/users.js"
    click DownloadRoutes "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/routes/download.js"
    click ElevenLabsRoutes "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/routes/elevenlabs.js"
    click GptsRoutes "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/routes/gpts.js"
    click LibraryRoutes "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/routes/library.js"
    click PublicRoutes "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/routes/public.js"
    click SearchRoutes "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/routes/search.js"
    click VideoRoutes "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/routes/video.js"
    click AiService "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/services/ai-service.js"
    click FileProcessor "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/services/fileProcessor.js"
    click UsageService "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/services/usage-service.js"
    click HelperSvc "https://github.com/hamzabhiinder/openwebuibackend/blob/main/src/services/helper.js"
    click PrismaSchema "https://github.com/hamzabhiinder/openwebuibackend/blob/main/prisma/schema.prisma"
    click Migrations "https://github.com/hamzabhiinder/openwebuibackend/tree/main/prisma/migrations/"
    click SeedScript "https://github.com/hamzabhiinder/openwebuibackend/blob/main/prisma/seed.js"
    click Scripts "https://github.com/hamzabhiinder/openwebuibackend/blob/main/scripts/setup-db.js"
    click UploadsDir "https://github.com/hamzabhiinder/openwebuibackend/tree/main/uploads/"
    click TesseractData "https://github.com/hamzabhiinder/openwebuibackend/blob/main/eng.traineddata"

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#1F618D,color:#1B4F72
    classDef datastore fill:#D5F5E3,stroke:#27AE60,color:#186A3B
    classDef external fill:#FAD7A0,stroke:#D68910,color:#7D6608
```
