# nicknochnack/sourcery architecture

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

- Interactive diagram: https://gitdiagram.com/nicknochnack/sourcery
- Repository: https://github.com/nicknochnack/sourcery

## Overview

##### Project type and purpose
- This is a full-stack web application (“Sourcery”) that helps procurement teams generate, distribute, and evaluate RFPs (requests for proposals) using generative AI.
- The backend is an Express/Node.js API with Knex/SQL and Passport for auth; the frontend is a React/Vite SPA styled with Tailwind.

##### Main components
a. Frontend (client/)
- React SPA (client/src)
- UI components (client/src/ui), pages (client/src/pages), utilities for HTTP and auth (client/src/utilities)
- Bundler: Vite (client/vite.config.js), Tailwind (client/tailwind.config.js)
b. Backend API (server.js + api/ + controller/ + model/)
- API routes (api/*.js)
- Controllers (controller/*Controller.js) implement business logic
- Models (model/*.js) wrapping Knex queries
- Middleware (middleware/passport.js) for authentication
- Utilities (utilities/*.js) for helper functions
c. Database
- PostgreSQL accessed via Knex; schema migrations live in migrations/
d. File storage
- uploads/rfp-responses holds uploaded Excel files
e. External AI service
- IBM watsonx AI (api/watsonx.js + controller/watsonxController.js)

##### Relationships & data flow
- The browser (user) sends HTTP(S) requests to the React SPA.
- SPA makes AJAX calls to the Express API (client/src/utilities/api.js).
- Express API routes → controllers → models → database for CRUD on users, RFPs, vendors, proposals, responses, approvals.
- For generative assistance, controllers call the Watsonx client → receive AI responses → return to SPA.
- File uploads (RFP responses) stream from frontend into Express → saved to uploads/ → processed by controllers → metadata stored in the DB.
- Authentication requests (login/signup) pass through Passport middleware → JWT or session → protected routes via PrivateRoute in React.

##### Architectural patterns & design principles
- Layered/MVC pattern:
- Route Layer (api/)
- Controller Layer (controller/)
- Data Access Layer (models + migrations)
- Separation of concerns: auth middleware isolated, utilities factored out, UI components decoupled.
- Single Page Application for the client, RESTful API on the server.
- External service integration encapsulated in its own module (watsonx).

- Blue = application components
- Orange = database & storage
- Green = external AI service

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global entities
    User["User"]:::user

    subgraph "Frontend SPA"
        direction TB
        FRSPA["React SPA"]:::app
        VITE["Vite Config"]:::app
        TAILWIND["Tailwind Config"]:::app
        UI["UI Components"]:::app
        PAGES["Pages"]:::app
        APIUTIL["HTTP Utilities"]:::app
        AUTHUTIL["Auth Utilities"]:::app
    end

    subgraph "Backend API"
        direction TB
        SERVER["Express API Entry (server.js)"]:::app
        ROUTES["API Routes"]:::app
        CONTROLLERS["Controllers"]:::app
        MODELS["Models"]:::app
        MIGRATIONS["Migrations"]:::storage
        PASSPORTMW["Auth Middleware"]:::app
        BACKUTILS["Backend Utilities"]:::app
    end

    subgraph "Database & Storage"
        direction TB
        DB["PostgreSQL DB"]:::storage
        FILESTORE["RFP Responses Storage"]:::storage
    end

    AI["IBM Watsonx AI"]:::external

    %% Connections
    User -->|"loads SPA"| FRSPA
    FRSPA -->|"HTTP(S) JSON"| SERVER
    SERVER -->|"Knex SQL"| DB
    SERVER -->|Excel upload| FILESTORE
    SERVER -->|"AI request/response"| AI
    SERVER -->|"Auth check"| PASSPORTMW
    SERVER -->|"use routes"| ROUTES
    ROUTES -->|"call logic"| CONTROLLERS
    CONTROLLERS -->|"query data"| MODELS
    MODELS -->|"migrations define schema"| MIGRATIONS
    BACKUTILS -->|"helpers"| CONTROLLERS
    FRSPA --> VITE
    FRSPA --> TAILWIND
    FRSPA --> UI
    FRSPA --> PAGES
    FRSPA --> APIUTIL
    FRSPA --> AUTHUTIL

    %% Click Events
    click FRSPA "https://github.com/nicknochnack/sourcery/tree/main/client/src"
    click UI "https://github.com/nicknochnack/sourcery/tree/main/client/src/ui"
    click PAGES "https://github.com/nicknochnack/sourcery/tree/main/client/src/pages"
    click APIUTIL "https://github.com/nicknochnack/sourcery/blob/main/client/src/utilities/api.js"
    click AUTHUTIL "https://github.com/nicknochnack/sourcery/blob/main/client/src/utilities/auth.js"
    click VITE "https://github.com/nicknochnack/sourcery/blob/main/client/vite.config.js"
    click TAILWIND "https://github.com/nicknochnack/sourcery/blob/main/client/tailwind.config.js"

    click SERVER "https://github.com/nicknochnack/sourcery/blob/main/server.js"
    click ROUTES "https://github.com/nicknochnack/sourcery/blob/main/api/index.js"
    click CONTROLLERS "https://github.com/nicknochnack/sourcery/blob/main/controller/userController.js"
    click MODELS "https://github.com/nicknochnack/sourcery/blob/main/model/knex.js"
    click MIGRATIONS "https://github.com/nicknochnack/sourcery/blob/main/migrations/20250108223508_user.js"
    click PASSPORTMW "https://github.com/nicknochnack/sourcery/blob/main/middleware/passport.js"
    click BACKUTILS "https://github.com/nicknochnack/sourcery/blob/main/utilities/utils.js"
    click FILESTORE "https://github.com/nicknochnack/sourcery/tree/main/uploads/rfp-responses/"
    click AI "https://github.com/nicknochnack/sourcery/blob/main/api/watsonx.js"

    %% Styles
    classDef app fill:#D0E8FF,stroke:#036,stroke-width:1px
    classDef storage fill:#FFEBCC,stroke:#E69500,stroke-width:1px
    classDef external fill:#DDFFDD,stroke:#3A7,stroke-width:1px
    classDef user fill:#F5F5F5,stroke:#999,stroke-width:1px
```
