# devitaliya22/statushive architecture

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

- Interactive diagram: https://gitdiagram.com/devitaliya22/statushive
- Repository: https://github.com/devitaliya22/statushive

## Overview

##### Project type and purpose
- This is a full-stack Next.js application that provides uptime/latency monitoring, health checks, and status pages for arbitrary domains.
- It exposes a web UI (React + Next.js App Router) for dashboard, configuration, and status pages.
- It offers a set of REST/edge API routes (Next.js server/edge functions) for pings, metrics ingestion, notifications, and status checks.
- It persists data in a relational database via Prisma and uses Redis for caching/rate-limiting. It also feeds real-time analytics into Tinybird pipelines. Authentication is handled with NextAuth.

##### File structure
- src/app – the Next.js “app” folder holds UI routes (landing, auth, dashboard, monitors, notifications, statuspage).
- src/app/api – Next.js API endpoints, subdivided into:
– auth (NextAuth)
– edge (geolocation-based monitoring at airport codes)
– health, monitors, notifications (add/send/test), statuspage, subdomain
- prisma – schema + migrations for the main database (e.g., PostgreSQL) including a PingLocation table
- src/lib – shared libraries for authOptions, db (Prisma + Redis), domain logic, env, utilities
- src/tinybird – Tinybird datasource definitions, pipes, and a seed script for analytics ingestion
- components & hooks – client UI components and React hooks for state, debounce, location, toast
- Configuration files – Next.js config (next.config.ts), Tailwind, PostCSS, ESLint, tsconfig, package.json

##### Main components & boundaries
a. Frontend (Browser)
– Next.js App Router pages & React components (src/app, src/components)
– Tailwind CSS + global styles
b. Backend (Server / Edge)
– Next.js API Routes (Node.js Lambdas / Edge Functions) under src/app/api
– NextAuth (+ session store in Redis or DB)
c. Database & Cache
– Prisma ORM → PostgreSQL (or other SQL)
– Redis for caching, session store, rate limiting
d. Analytics / BI
– Tinybird: HTTP ingestion from server routes → datasources → pipes → public endpoints for dashboards
e. External Services
– Notification providers: Discord, Slack, Email (via SMTP or 3rd-party)
– Domain registry API (subdomain availability checks)
– Hosting/CDN: Vercel (edge functions for geo routes)

##### Relationships & data flows
1. User interacts with the Next.js UI → SSR/React hydration → client side fetches data via built-in fetch hooks or custom query providers.
2. UI → Next.js server/api routes for CRUD operations on monitors, notifications, status pages.
3. API routes → Prisma → SQL DB for persisting pings, monitor configs, users, notifications.
4. API routes → Redis for caching hot data (recent pings, rate limits, sessions).
5. Ping ingest endpoints (edge functions) execute in geo-distributed edge at airport codes → write ping records → optionally push aggregated events to Tinybird.
6. Tinybird pipelines process raw ping data → expose real-time analytics endpoints → consumed by UI or external dashboards.
7. Notification flows: when a monitor fails → backend calls /notifications/send/* routes → picks provider (Discord/Slack/Email) → calls external API/SNMP.

##### Architectural patterns & principles
- Monorepo with colocated frontend & backend (Next.js App Router)
- API-first design: every feature has a matching API route under src/app/api
- Edge functions for low-latency geo monitoring
- Shared domain library (src/lib/domain) for business logic, DRY across routes
- Data pipelines (Tinybird) for real-time analytics, separate from the primary DB
- Modular UI components & providers for theming, state, queries
- Secure auth via NextAuth and environment variables

##### Detailed elements
- For each API group (auth, monitors, edge, notifications) show one representative endpoint.
- Shared lib/domain and lib/env as an inset library used by all backend components.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients Layer
    subgraph "Clients" 
        direction TB
        Browser["Browser UI"]:::frontend
        CLI["CLI/cURL (Pings)"]:::external
    end

    %% Frontend/UI Layer
    subgraph "Frontend (Next.js App Router)" 
        direction TB
        Landing["Landing Page"]:::frontend
        Dashboard["Dashboard & Routes"]:::frontend
        SignIn["Auth Sign-in Page"]:::frontend
        StatusUI["Status Page UI"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Next.js Server & Edge)" 
        direction TB
        subgraph "API Routes" 
            direction TB
            AuthAPI["Auth API (NextAuth)"]:::backend
            HealthAPI["Health Check API"]:::backend
            MonitorsAPI["Monitors CRUD API"]:::backend
            EdgePing["Edge Ping Ingestion"]:::backend
            NotificationsAPI["Notifications API"]:::backend
            StatusPageAPI["StatusPage Config API"]:::backend
            SubdomainAPI["Subdomain Availability API"]:::backend
        end
        subgraph "Shared Libraries" 
            direction TB
            AuthOptions["NextAuth Options"]:::backend
            PrismaClient["Prisma Client"]:::backend
            RedisClient["Redis Integration"]:::backend
            DomainLogic["Domain Logic & Types"]:::backend
            EnvConfig["Env Variables & Validation"]:::backend
            Utils["Utility Functions"]:::backend
        end
    end

    %% Datastores Layer
    subgraph "Datastores" 
        direction TB
        SQLDB["PostgreSQL (Prisma)"]:::datastore
        RedisDB["Redis"]:::datastore
    end

    %% Analytics Layer
    subgraph "Analytics (Tinybird)" 
        direction TB
        TBIngest["Tinybird Ingestion"]:::analytics
        TBDatasources["Datasources & Pipes"]:::analytics
    end

    %% External Services Layer
    subgraph "External Services" 
        direction TB
        NotificationsExt["Discord/Slack/Email APIs"]:::external
        DomainRegistry["Domain Registry API"]:::external
        Vercel["Vercel Hosting/CDN"]:::external
    end

    %% Connections
    Browser -->|"SSR/Hydration & fetch"| Landing
    Browser -->|navigate| Dashboard
    Browser -->|navigate| SignIn
    Browser -->|navigate| StatusUI
    Browser -->|"fetch CRUD"| MonitorsAPI
    CLI -->|POST ping| EdgePing

    Landing -->|UI render| Dashboard
    Dashboard -->|fetch data| MonitorsAPI
    SignIn -->|auth request| AuthAPI
    StatusUI -->|fetch status| StatusPageAPI

    AuthAPI -->|use| AuthOptions
    MonitorsAPI -->|use| PrismaClient
    MonitorsAPI -->|cache| RedisClient
    HealthAPI -->|ping| SQLDB
    EdgePing -->|write ping| SQLDB
    EdgePing -->|push aggregate| TBIngest
    NotificationsAPI -->|trigger| NotificationsExt
    StatusPageAPI -->|read/write| SQLDB
    SubdomainAPI -->|check| DomainRegistry

    MonitorsAPI -->|DB ops| SQLDB
    HealthAPI -->|DB ops| SQLDB
    EdgePing -->|rate-limit| RedisClient

    TBIngest -->|process| TBDatasources
    TBDatasources -->|public endpoints| Browser

    Vercel -->|hosts| EdgePing
    Vercel -->|hosts| AuthAPI
    Vercel -->|hosts| HealthAPI

    %% Shared libs usage
    AuthAPI -->|use| EnvConfig
    MonitorsAPI -->|use| DomainLogic
    NotificationsAPI -->|use| EnvConfig
    EdgePing -->|use| Utils

    %% Click Events - Frontend
    click Landing "https://github.com/devitaliya22/statushive/blob/main/src/app/landing/page.tsx"
    click Dashboard "https://github.com/devitaliya22/statushive/tree/main/src/app/app/(main)"
    click SignIn "https://github.com/devitaliya22/statushive/blob/main/src/app/app/auth/signin/page.tsx"
    click StatusUI "https://github.com/devitaliya22/statushive/blob/main/src/app/[domain]/page.tsx"
    click StatusUI "https://github.com/devitaliya22/statushive/blob/main/src/app/app/(main)/statuspage/[id]/page.tsx"

    %% Click Events - API Routes
    click AuthAPI "https://github.com/devitaliya22/statushive/blob/main/src/app/api/auth/[...nextauth]/route.ts"
    click HealthAPI "https://github.com/devitaliya22/statushive/blob/main/src/app/api/health/route.ts"
    click MonitorsAPI "https://github.com/devitaliya22/statushive/blob/main/src/app/api/monitors/route.ts"
    click MonitorsAPI "https://github.com/devitaliya22/statushive/blob/main/src/app/api/monitors/[monitorId]/route.ts"
    click EdgePing "https://github.com/devitaliya22/statushive/blob/main/src/app/api/edge/edge.ts"
    click NotificationsAPI "https://github.com/devitaliya22/statushive/blob/main/src/app/api/notifications/add/discord/route.ts"
    click NotificationsAPI "https://github.com/devitaliya22/statushive/blob/main/src/app/api/notifications/send/discord/route.ts"
    click NotificationsAPI "https://github.com/devitaliya22/statushive/blob/main/src/app/api/notifications/test/discord/route.ts"
    click NotificationsAPI "https://github.com/devitaliya22/statushive/blob/main/src/app/api/notifications/getTestedEmails/route.ts"
    click StatusPageAPI "https://github.com/devitaliya22/statushive/blob/main/src/app/api/statuspage/route.ts"
    click SubdomainAPI "https://github.com/devitaliya22/statushive/blob/main/src/app/api/subdomain/available/route.ts"

    %% Click Events - Libraries
    click PrismaClient "https://github.com/devitaliya22/statushive/blob/main/src/lib/db/prisma.ts"
    click RedisClient "https://github.com/devitaliya22/statushive/blob/main/src/lib/db/redis.ts"
    click AuthOptions "https://github.com/devitaliya22/statushive/blob/main/src/lib/auth/authOptions.ts"
    click DomainLogic "https://github.com/devitaliya22/statushive/blob/main/src/lib/domain/domain.ts"
    click EnvConfig "https://github.com/devitaliya22/statushive/blob/main/src/lib/env/env.ts"
    click Utils "https://github.com/devitaliya22/statushive/blob/main/src/lib/utils.ts"

    %% Click Events - Analytics
    click TBDatasources "https://github.com/devitaliya22/statushive/blob/main/src/tinybird/datasource/status_checks.datasource"
    click TBDatasources "https://github.com/devitaliya22/statushive/blob/main/src/tinybird/pipes/monitor_aggregates.pipe"
    click TBDatasources "https://github.com/devitaliya22/statushive/blob/main/src/tinybird/pipes/regional_latency.pipe"
    click TBDatasources "https://github.com/devitaliya22/statushive/blob/main/src/tinybird/pipes/regional_performance.pipe"
    click TBIngest "https://github.com/devitaliya22/statushive/blob/main/src/tinybird/seed.ts"
    click TBIngest "https://github.com/devitaliya22/statushive/blob/main/src/tinybird/tinybird.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef backend fill:#D0F0C0,stroke:#333,stroke-width:1px
    classDef datastore fill:#FFE0A0,stroke:#333,stroke-width:1px
    classDef analytics fill:#E8D0FF,stroke:#333,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#333,stroke-width:1px
```
