# fixadev/fixa-observe architecture

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

- Interactive diagram: https://gitdiagram.com/fixadev/fixa-observe
- Repository: https://github.com/fixadev/fixa-observe

## Overview

##### Main System Components

The system consists of three main applications and several shared packages:

a. Web Application (apps/web-app)
- Next.js frontend application
- Handles user interface and interactions
- Contains authentication flows (Clerk integration)
- Dashboard for monitoring and testing

b. Node Server (apps/node-server)
- Main backend API service
- Handles business logic and integrations
- Manages authentication and authorization
- Processes voice agent interactions

c. Transcription Service (apps/transcription-service)
- Python-based service for audio processing
- Handles voice transcription
- Channel splitting functionality

##### Key Integration Points

- Clerk for authentication
- Stripe for payments
- AWS S3 for file storage
- PostHog for analytics
- OpenAI for AI capabilities
- Slack for notifications
- VAPI for voice agent interactions

**┌─ Client Layer ─────────────────────┐**
- Web Application (Next.js)          │
- Dashboard                        │
- Testing Interface               │
- Monitoring Tools                │
- ┬───────────────────┘

**┌───────────────▼───────────────────┐**
- API Layer (Node Server)           │
- REST Endpoints                  │
- WebSocket Connections           │
- Authentication Middleware       │
- ┬───────────────────┘

**┌───────────────▼───────────────────┐**
- Service Layer                     │
- ┌─────────────┐  ┌──────────────┐ │
- Node Server  │  │Transcription │ │
- Services     │  │Service       │ │
- ┘  └──────────────┘ │
- ┬───────────────────┘

**┌───────────────▼───────────────────┐**
- External Services                 │
- Clerk (Auth)                   │
- Stripe (Payments)              │
- S3 (Storage)                   │
- PostHog (Analytics)            │
- OpenAI (AI)                    │
- Slack (Notifications)          │
- VAPI (Voice Agents)            │
- ┘

##### Data Flow Indicators

- User request flows
- Authentication paths
- File upload/download routes
- WebSocket connections
- Service-to-service communication

##### Additional Elements

Components:
- Database schema representation
- Queue systems for async processing
- Error handling flows
- Monitoring and logging paths

##### Deployment Context

Deployment-related information:
- Fly.io deployment configurations
- Docker container relationships
- Environment-specific components

##### Security Boundaries

Security zones:
- Public endpoints
- Protected routes
- Admin-only areas
- API authentication boundaries

Remember to maintain a balance between detail and clarity, focusing on the core architecture while providing enough information for understanding the system's complexity and interactions.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        WA["Web Application"]
        DB["Dashboard"]:::dashboard
        TI["Testing Interface"]
        MT["Monitoring Tools"]
        UI["UI Components"]:::ui
        Auth["Authentication"]:::auth
    end

    subgraph API
        NS["Node Server"]:::server
        API["API Routes"]:::api
        WS["WebSocket Connections"]
        AM["Auth Middleware"]:::auth
    end

    subgraph Services
        NSS["Node Services"]:::server
        TS["Transcription Service"]:::service
        CS["Channel Splitting"]:::service
        TL["Transcription Logic"]:::service
    end

    subgraph External
        Clerk["Clerk Auth"]:::external
        Stripe["Stripe Payments"]:::external
        S3["AWS S3"]:::external
        PH["PostHog Analytics"]:::external
        OAI["OpenAI"]:::external
        Slack["Slack"]:::external
        VAPI["VAPI"]:::external
    end

    subgraph Shared
        Schema["Database Schema"]:::db
        Types["Types"]:::shared
        SS["Shared Services"]:::shared
        SC["Shared Components"]:::shared
    end

    %% Client Layer Connections
    WA --> DB
    WA --> TI
    WA --> MT
    WA --> UI
    WA --> Auth

    %% API Layer Connections
    Auth --> NS
    NS --> API
    NS --> WS
    NS --> AM

    %% Service Layer Connections
    NS --> NSS
    NSS --> TS
    TS --> CS
    TS --> TL

    %% External Service Connections
    NS --> Clerk
    NS --> Stripe
    NS --> S3
    NS --> PH
    NS --> OAI
    NS --> Slack
    NS --> VAPI

    %% Shared Resource Connections
    NS --> Schema
    NS --> Types
    NS --> SS
    WA --> SC

    %% Click Events
    click WA "https://github.com/fixadev/fixa-observe/tree/main/apps/web-app/src/app"
    click DB "https://github.com/fixadev/fixa-observe/tree/main/apps/web-app/src/app/dashboard"
    click Auth "https://github.com/fixadev/fixa-observe/tree/main/apps/web-app/src/app/(clerk)"
    click UI "https://github.com/fixadev/fixa-observe/tree/main/apps/web-app/src/components"
    click NS "https://github.com/fixadev/fixa-observe/tree/main/apps/node-server/src"
    click API "https://github.com/fixadev/fixa-observe/tree/main/apps/node-server/src/routers/v1/routes"
    click NSS "https://github.com/fixadev/fixa-observe/tree/main/apps/node-server/src/services"
    click AM "https://github.com/fixadev/fixa-observe/tree/main/apps/node-server/src/middlewares"
    click TS "https://github.com/fixadev/fixa-observe/tree/main/apps/transcription-service/src"
    click CS "https://github.com/fixadev/fixa-observe/blob/main/apps/transcription-service/src/services/split_channels.py"
    click TL "https://github.com/fixadev/fixa-observe/blob/main/apps/transcription-service/src/services/transcribe.py"
    click Clerk "https://github.com/fixadev/fixa-observe/blob/main/apps/node-server/src/clients/clerkServiceClient.ts"
    click Stripe "https://github.com/fixadev/fixa-observe/blob/main/apps/node-server/src/clients/stripeServiceClient.ts"
    click S3 "https://github.com/fixadev/fixa-observe/blob/main/apps/node-server/src/clients/s3Client.ts"
    click PH "https://github.com/fixadev/fixa-observe/blob/main/apps/node-server/src/clients/posthogClient.ts"
    click OAI "https://github.com/fixadev/fixa-observe/blob/main/apps/node-server/src/clients/openAIClient.ts"
    click VAPI "https://github.com/fixadev/fixa-observe/blob/main/apps/node-server/src/clients/vapiClient.ts"
    click Slack "https://github.com/fixadev/fixa-observe/blob/main/apps/node-server/src/services/slack.ts"
    click Schema "https://github.com/fixadev/fixa-observe/blob/main/packages/db/src/schema.prisma"
    click Types "https://github.com/fixadev/fixa-observe/tree/main/packages/types/src"
    click SS "https://github.com/fixadev/fixa-observe/tree/main/packages/services/src"
    click SC "https://github.com/fixadev/fixa-observe/tree/main/packages/ui/src"

    %% Styling
    classDef default fill:#f9f9f9,stroke:#333,stroke-width:2px
    classDef server fill:#2496ed,color:white
    classDef service fill:#ff9900,color:white
    classDef external fill:#95c93d,color:white
    classDef db fill:#f68d2e,color:white
    classDef shared fill:#8a2be2,color:white
    classDef auth fill:#9932cc,color:white
    classDef api fill:#1e90ff,color:white
    classDef dashboard fill:#4169e1,color:white
    classDef ui fill:#4682b4,color:white
```
