# vibinex/vibinex-server architecture

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

- Interactive diagram: https://gitdiagram.com/vibinex/vibinex-server
- Repository: https://github.com/vibinex/vibinex-server

## Overview

##### Project type and purpose
- This is a full-stack Next.js application that serves two main roles:
a. The public website (vibinex.com) with React pages under `pages/` and UI components in `components/` and `views/`.
b. The primary backend for the Vibinex Browser Extension, handling OAuth authentication, API routes, analytics, metadata storage, and security.
- It integrates with an on-prem Rust microservice (outside this repo) for heavy code-history processing, and uses a PostgreSQL database for persistence.

##### File structure
- Top-level directories:
- `pages/`: Next.js pages and API routes (`pages/api/...`).
- `components/` & `views/`: React components and view templates for pages.
- `utils/`: Helper modules (DB adapters under `utils/db`, provider API clients under `utils/providerAPI`, pub/sub client, encryption, etc.).
- `public/`, `styles/`, `types/`: Static assets, CSS/Tailwind configs, and TypeScript types.
- Config & build: `next.config.js`, `app.yaml`, `cloudbuild.yaml`, GitHub Actions workflow in `.github/`.

##### Main components
1. Start Node (Sequence 1) – “User action” (browser extension event or website request).
2. Next.js Frontend (Seq 2) – React pages under `pages/` serve UI.
3. NextAuth API (Seq 3) – `pages/api/auth/[...nextauth].ts` handles OAuth flow with GitHub/Bitbucket/GitLab.
4. OAuth Providers (Seq 4) – External Git providers validate credentials and return tokens.
5. Next.js Backend API (Seq 5) – Other `pages/api/*` endpoints process requests (repo selection, trigger events, docs, analytics).
6. Provider API Clients (Seq 6) – Modules in `utils/providerAPI` call GitHub/Bitbucket APIs to fetch repos, webhooks, etc.
7. Pub/Sub (Seq 7) – `utils/pubsub/pubsubClient.ts` publishes/subscribes to events for asynchronous processing.
8. PostgreSQL Database (Seq 8) – Persist metadata via `utils/db/*.ts` (aliases, healthStatus, repos, users).
9. On-Prem Rust Service (Seq 9) – Invoked for heavy code-history analysis, reviewer assignment, comment generation.
10. Next.js API returns enriched data (Seq 10) – Combines DB records and Rust-processed metadata.
11. Browser Extension UI / Website (Seq 11) – Renders personalized highlights and review data.
12. End Node (Sequence 12) – “Flow complete” – enriched PR UI displayed.

##### Relationships and interactions
1 → 2 → 3 → 4 → 3 → 5 → 6 → 7 → 8 → 9 → 8 → 10 → 11 → 12
- Both synchronous flows (Auth, API requests) and asynchronous flows (Pub/Sub → Rust service).

##### Architectural patterns & design principles
- Separation of concerns: React UI vs. Next.js API routes vs. DB adapter vs. external microservice.
- Modular provider clients (`utils/providerAPI`) and database layer (`utils/db`) for easy extension.
- Pub/Sub for decoupled, asynchronous background processing.
- NextAuth.js for pluggable OAuth flows.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Start and End
    Start(("1. Start: User Action")):::ui
    End(("12. End: Enriched UI Displayed")):::ui

    %% Components
    Frontend["2. Next.js Frontend (React Pages & UI)"]:::ui
    AuthAPI["3. NextAuth OAuth API"]:::api
    OAuthProvider([/ OAuth Providers /]):::external
    BackendAPI["5. Next.js Backend API Routes"]:::api
    ProviderClients["6. Provider API Clients"]:::external
    PubSub([Pub/Sub Client]):::pubsub
    Database[(PostgreSQL Database)]:::db
    RustService{{On-Prem Rust Service}}:::micro
    EnrichedAPI["10. Next.js API Returns Enriched Data"]:::api
    BrowserUI["11. Browser Extension UI / Website"]:::ui

    %% Connections
    Start -->|"1→2"| Frontend
    Frontend -->|"2→3"| AuthAPI
    AuthAPI -->|"3→4"| OAuthProvider
    OAuthProvider -->|"4→3"| AuthAPI
    AuthAPI -->|"3→5"| BackendAPI
    BackendAPI -->|"5→6"| ProviderClients
    ProviderClients -->|"6→7"| PubSub
    PubSub -->|"7→8"| Database
    Database -->|"8→9"| RustService
    RustService -->|"9→8"| Database
    Database -->|"8→10"| EnrichedAPI
    EnrichedAPI -->|"10→11"| BrowserUI
    BrowserUI -->|"11→12"| End

    %% Click Events
    click Frontend "https://github.com/vibinex/vibinex-server/tree/main//pages/"
    click Frontend "https://github.com/vibinex/vibinex-server/tree/main//components/"
    click Frontend "https://github.com/vibinex/vibinex-server/tree/main//views/"
    click AuthAPI "https://github.com/vibinex/vibinex-server/blob/main/pages/api/auth/[...nextauth].ts"
    click BackendAPI "https://github.com/vibinex/vibinex-server/tree/main/pages/api/"
    click ProviderClients "https://github.com/vibinex/vibinex-server/tree/main/utils/providerAPI/"
    click PubSub "https://github.com/vibinex/vibinex-server/blob/main/utils/pubsub/pubsubClient.ts"
    click Database "https://github.com/vibinex/vibinex-server/blob/main/utils/db/index.ts"

    %% Styles
    classDef ui fill:#add8e6,stroke:#333,stroke-width:1px
    classDef api fill:#90ee90,stroke:#333,stroke-width:1px
    classDef external fill:#f08080,stroke:#333,stroke-width:1px
    classDef db fill:#ffa500,stroke:#333,stroke-width:1px
    classDef micro fill:#dda0dd,stroke:#333,stroke-width:1px
    classDef pubsub fill:#ffcc00,stroke:#333,stroke-width:1px
```
