# d47r48yy6/starbridge_ai architecture

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

- Interactive diagram: https://gitdiagram.com/d47r48yy6/starbridge_ai
- Repository: https://github.com/d47r48yy6/starbridge_ai

## Overview

##### Project type and purpose
- This is a full-stack, server-side-rendered (SSR) web application built on Next.js.
- Purpose: An AI-Powered Interview Platform that generates role-specific questions, conducts voice interviews, analyzes responses, and stores feedback.

##### File structure
- app/ – Next.js App Router drives pages, layouts, and server actions.
- (auth) – Sign-in & sign-up flows
- (root)/interview – Interview listing, individual interview session, feedback pages
- api/vapi/generate – Serverless route for AI question/voice generation
- components/ui – Design system primitives (button, form, input, label)
- lib/actions – Business logic and abstractions for auth, general flows
- firebase/ – Firebase admin & client SDK wrappers
- public/ – Static assets (covers)
- constants/, types/, utils – Shared constants, TS types, utility functions
- next.config.ts, eslint.config.mjs, postcss.config.mjs – Build, lint, styling configs

##### README for additional insights
- Key services: Next.js SSR, Firebase Auth/Firestore, OpenAI GPT & Google Studio API (question gen), Vapi AI (voice interface)
- Architecture hints: Server-side routes for AI calls, Firebase-driven backend for user data & NLP evaluation

##### Main components & how to represent them
a. Frontend (Client Browser)
- Next.js pages & components
- React-based UI in components/ui
- CSS via globals.css + Tailwind/PostCSS
b. Server-Side (Next.js / Vercel)
- SSR compute and server actions in app/…/route.ts
- API Route: /api/vapi/generate → orchestrates GPT + Google Studio + Vapi AI
- Firebase client SDK for auth + Firestore queries
c. Backend Services
- Firebase Auth: user sign-up, sign-in
- Firebase Firestore: store interview sessions, responses, feedback
- Firebase Cloud Functions (optional for NLP evaluation) via firebase/admin.ts
d. External AI Services
- OpenAI GPT & Google Studio API: dynamic question generation
- Vapi AI: voice interaction, text-to-speech & speech-to-text
e. Data Flows
- User → Browser → Next.js SSR → API routes → AI Services → Response → Browser
- Browser → Firebase Auth → Firestore → Browser
- AI-generated feedback stored in Firestore → Retrieved on feedback pages

##### Architectural patterns & design principles
- Folder-based routing (Next.js App Router)
- Separation of concerns: UI components vs. business logic (lib/actions)
- Serverless functions for “backend” endpoints
- Single-source truth for types (types/) and constants (constants/)
- Design system in components/ui for consistency

##### Elements
- Clear labels: “Next.js SSR”, “API Route: /api/vapi/generate”, “Firestore”, “OpenAI GPT”, “Vapi AI”
- Blue for client-side layers
- Green for serverless/API layers
- Orange for external AI services
- Yellow for data stores (Firestore)
- Rectangles for compute layers (SSR, API, Cloud Functions)
- Clouds for external services

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Browser
    subgraph "Client Browser" 
        direction TB
        User["User"]:::frontend
        subgraph "Next.js App Router (SSR pages & layouts)" 
            direction TB
            A1["app/layout.tsx"]:::frontend
            A2["app/(root)/layout.tsx"]:::frontend
            A3["app/(root)/page.tsx"]:::frontend
        end
        subgraph "Authentication Flows" 
            direction TB
            B1["app/(auth)/layout.tsx"]:::frontend
            B2["app/(auth)/sign-in/page.tsx"]:::frontend
            B3["app/(auth)/sign-up/page.tsx"]:::frontend
        end
        subgraph "Interview Pages" 
            direction TB
            C1["app/(root)/interview/page.tsx"]:::frontend
            C2["app/(root)/interview/[id]/page.tsx"]:::frontend
            C3["app/(root)/interview/[id]/feedback/page.tsx"]:::frontend
        end
        subgraph "UI Components & Design System"
            direction TB
            D1["components/Agent.tsx"]:::frontend
            D2["components/AuthForm.tsx"]:::frontend
            D3["components/InterviewCard.tsx"]:::frontend
            D4["components/DisplayTechIcons.tsx"]:::frontend
            D5["components/FormField.tsx"]:::frontend
            E1["components/ui/button.tsx"]:::frontend
            E2["components/ui/form.tsx"]:::frontend
            E3["components/ui/input.tsx"]:::frontend
            E4["components/ui/label.tsx"]:::frontend
            E5["components/ui/sonner.tsx"]:::frontend
        end
        subgraph "Business Logic & Utilities"
            direction TB
            F1["lib/actions/auth.action.ts"]:::backend
            F2["lib/actions/general.action.ts"]:::backend
            F3["lib/vapi.sdk.ts"]:::backend
            F4["lib/utils.ts"]:::backend
        end
        subgraph "Firebase SDK Wrappers"
            direction TB
            G1["firebase/client.ts"]:::backend
            G2["firebase/admin.ts"]:::backend
        end
        subgraph "Shared Constants & Types"
            direction TB
            H1["constants/index.ts"]:::backend
            H2["types/index.d.ts"]:::backend
            H3["types/vapi.d.ts"]:::backend
        end
    end

    %% Serverless/API Layer
    subgraph "Next.js SSR / Vercel" 
        direction TB
        SSR["SSR pages & server actions"]:::backend
        API["API Route: /api/vapi/generate"]:::backend
    end

    %% External AI Services
    subgraph "External AI Services"
        direction TB
        OpenAI["OpenAI GPT & Google Studio"]:::external
        VapiAI["Vapi AI"]:::external
    end

    %% Firebase Services
    subgraph "Firebase Backend"
        direction TB
        Auth["Firebase Auth"]:::datastore
        Firestore["Firestore DB"]:::datastore
        Functions["Cloud Functions (NLP Eval)"]:::datastore
    end

    %% Connections
    User -->|uses| A1
    User -->|uses| B1
    User -->|navigates| C1
    A3 -->|SSR render| SSR
    SSR -->|calls| API
    API -->|"generate questions"| OpenAI
    API -->|"voice processing"| VapiAI
    User -->|auth| Auth
    SSR -->|read/write| Firestore
    VapiAI -->|store transcripts| Firestore
    Functions -->|analyze feedback| Firestore
    Firestore -->|fetch feedback| C3

    %% Click Events
    click A1 "https://github.com/d47r48yy6/starbridge_ai/blob/main/app/layout.tsx"
    click A2 "https://github.com/d47r48yy6/starbridge_ai/blob/main/app/(root)/layout.tsx"
    click A3 "https://github.com/d47r48yy6/starbridge_ai/blob/main/app/(root)/page.tsx"
    click B1 "https://github.com/d47r48yy6/starbridge_ai/blob/main/app/(auth)/layout.tsx"
    click B2 "https://github.com/d47r48yy6/starbridge_ai/blob/main/app/(auth)/sign-in/page.tsx"
    click B3 "https://github.com/d47r48yy6/starbridge_ai/blob/main/app/(auth)/sign-up/page.tsx"
    click C1 "https://github.com/d47r48yy6/starbridge_ai/blob/main/app/(root)/interview/page.tsx"
    click C2 "https://github.com/d47r48yy6/starbridge_ai/blob/main/app/(root)/interview/[id]/page.tsx"
    click C3 "https://github.com/d47r48yy6/starbridge_ai/blob/main/app/(root)/interview/[id]/feedback/page.tsx"
    click API "https://github.com/d47r48yy6/starbridge_ai/blob/main/app/api/vapi/generate/route.ts"
    click D1 "https://github.com/d47r48yy6/starbridge_ai/blob/main/components/Agent.tsx"
    click D2 "https://github.com/d47r48yy6/starbridge_ai/blob/main/components/AuthForm.tsx"
    click D3 "https://github.com/d47r48yy6/starbridge_ai/blob/main/components/InterviewCard.tsx"
    click D4 "https://github.com/d47r48yy6/starbridge_ai/blob/main/components/DisplayTechIcons.tsx"
    click D5 "https://github.com/d47r48yy6/starbridge_ai/blob/main/components/FormField.tsx"
    click E1 "https://github.com/d47r48yy6/starbridge_ai/blob/main/components/ui/button.tsx"
    click E2 "https://github.com/d47r48yy6/starbridge_ai/blob/main/components/ui/form.tsx"
    click E3 "https://github.com/d47r48yy6/starbridge_ai/blob/main/components/ui/input.tsx"
    click E4 "https://github.com/d47r48yy6/starbridge_ai/blob/main/components/ui/label.tsx"
    click E5 "https://github.com/d47r48yy6/starbridge_ai/blob/main/components/ui/sonner.tsx"
    click F1 "https://github.com/d47r48yy6/starbridge_ai/blob/main/lib/actions/auth.action.ts"
    click F2 "https://github.com/d47r48yy6/starbridge_ai/blob/main/lib/actions/general.action.ts"
    click F3 "https://github.com/d47r48yy6/starbridge_ai/blob/main/lib/vapi.sdk.ts"
    click F4 "https://github.com/d47r48yy6/starbridge_ai/blob/main/lib/utils.ts"
    click G1 "https://github.com/d47r48yy6/starbridge_ai/blob/main/firebase/client.ts"
    click G2 "https://github.com/d47r48yy6/starbridge_ai/blob/main/firebase/admin.ts"
    click H1 "https://github.com/d47r48yy6/starbridge_ai/blob/main/constants/index.ts"
    click H2 "https://github.com/d47r48yy6/starbridge_ai/blob/main/types/index.d.ts"
    click H3 "https://github.com/d47r48yy6/starbridge_ai/blob/main/types/vapi.d.ts"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#2a7fdb;
    classDef backend fill:#d4edda,stroke:#28a745;
    classDef external fill:#fff3cd,stroke:#ff8800;
    classDef datastore fill:#fff5e6,stroke:#e6a700;
```
