# icoretech/airbroke architecture

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

- Interactive diagram: https://gitdiagram.com/icoretech/airbroke
- Repository: https://github.com/icoretech/airbroke

## Overview

##### Main Components
- Frontend/UI: Built with React/Next.js residing in the “app” directory. Includes pages for bookmarks, projects, sign-in, error occurrence display, etc.
- API Endpoints: Located under “app/api” with further subdivisions:
– Auth endpoints (for NextAuth-based user authentication)
– Data Collection API endpoints (receiving error reports and performing in-band error processing)
– Health-check endpoints and v3 endpoints for notices.
- Authentication Layer: Supported via NextAuth with multiple providers (GitHub, Google, etc.) and configured via environment variables in .env.
- Database: PostgreSQL accessed via Prisma (see the “prisma” folder with migrations, schema.prisma, and seed.ts).
- Utility & Business Logic: Code in “lib” (for actions, error processing, integrations, queries, etc.) that handles key logic such as generating updated URLs or parsing notices.
- Testing: __tests__ directory contains tests for API endpoints, pages, and libraries.
- Deployment & DevOps: Supporting files like Dockerfile, docker-compose.yml, GitHub workflows, and Makefile indicate multiple deployment scenarios including Docker image builds and Kubernetes deployments.

##### Relationships and Data Flow
- Clients (browsers) interact with the front-end UI hosted as Next.js pages.
- The frontend communicates with underlying API routes (HTTP endpoints) to perform key tasks like error ingestion, authentication, fetching error details, managing projects, and more.
- The Data Collection API endpoint receives error reports (using an Airbrake-compatible HTTP collector endpoint) and processes them synchronously.
- The authentication layer, based on NextAuth, sits between the client and the API, handling user sessions and OAuth provider integrations.
- Both the frontend and the API interact with the PostgreSQL database using Prisma; one connection (via DATABASE_URL) is for in-app operations while DIRECT_URL is used for migrations in deployment contexts.
- The DevOps setup (Docker, docker-compose, GitHub Actions, Render, Vercel, Helm chart etc.) is used to build, test, and deploy the entire system.

##### Architectural Patterns and Design Choices
- All-in-One Next.js Application: The project uses Next.js’s hybrid model where the frontend and backend APIs coexist in a single codebase.
- Server-Side Rendering (SSR) and Static Generation: The use of Next.js implies usage of optimized page rendering for performance.
- Modular Component-based UI: The “components” directory is rich with reusable React components (e.g., for occurrence charts, bookmarks, confirmation dialogs).
- API Route Segmentation: The API endpoints are structured using path-based routing (e.g., /api/auth, /api/completion), helping to separate concerns (authentication, error collection, notice management).
- Database Schema & Migrations: The “prisma” folder shows that the project uses migrations for schema evolution, encapsulating database design.
- Containerization: Docker configurations and related scripts show that containerization is employed, making the system deployment-ready across multiple environments.

- Connections: Use annotations or call-outs near API endpoints to mention that they are Airbrake-compatible and process error reports synchronously.
- Deployment Options: Include optional branches for deployment mechanisms (Docker, Vercel, Render, Helm) to demonstrate the flexible multi-deployment approach.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Client("User Browser"):::client

    %% Application Server Subgraph
    subgraph "Application Server"
        Frontend("Next.js Frontend (React, Tailwind CSS)"):::frontend
        API("API Endpoints (/api)"):::backend
        Auth("Authentication Module (NextAuth)"):::backend
        Utilities("Utility & Business Logic (lib)"):::utility
        UIComponents("Modular UI Components (components)"):::frontend
    end

    %% Database Component
    Database("PostgreSQL Database (Prisma ORM)"):::database

    %% Deployment & DevOps Subgraph
    subgraph "Deployment & DevOps"
        DeployDocker("Dockerfile Config"):::deployment
        DeployCompose("Docker Compose Config"):::deployment
        DeployMake("Makefile"):::deployment
        DeployGitHub("GitHub Workflows"):::deployment
    end

    %% Testing Suite
    Testing("Testing Suite (__tests__)"):::testing

    %% Connections / Data Flow
    Client -->|"accesses"| Frontend
    Frontend -->|"API calls"| API
    API -->|"handles auth"| Auth
    API -->|"invokes logic"| Utilities
    API -->|"stores/retrieves"| Database
    Utilities -->|"queries/upserts"| Database
    Frontend -->|"renders"| UIComponents
    Testing ---|"validates"| API

    %% Deployment Influence (dotted arrows indicate deployment pipeline links)
    DeployDocker -.->|"deploys"| Frontend
    DeployCompose -.->|"deploys"| API
    DeployMake -.->|"orchestrates"| Utilities
    DeployGitHub -.->|"CI/CD triggers"| Database

    %% Classes / Styles
    classDef client fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef frontend fill:#ffebcc,stroke:#333,stroke-width:2px;
    classDef backend fill:#d1e7dd,stroke:#333,stroke-width:2px;
    classDef utility fill:#e2e3e5,stroke:#333,stroke-width:2px;
    classDef database fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef deployment fill:#d1d1e0,stroke:#333,stroke-width:2px;
    classDef testing fill:#ffe6f2,stroke:#333,stroke-width:2px;

    %% Click Events for Component Mapping
    click Frontend "https://github.com/icoretech/airbroke/blob/main/app/page.tsx"
    click API "https://github.com/icoretech/airbroke/tree/main/app/api"
    click Auth "https://github.com/icoretech/airbroke/tree/main/app/api/auth"
    click Utilities "https://github.com/icoretech/airbroke/blob/main/lib/db.ts"
    click UIComponents "https://github.com/icoretech/airbroke/tree/main/components"
    click Database "https://github.com/icoretech/airbroke/blob/main/prisma/schema.prisma"
    click Testing "https://github.com/icoretech/airbroke/tree/main/__tests__"
    click DeployDocker "https://github.com/icoretech/airbroke/tree/main/Dockerfile"
    click DeployCompose "https://github.com/icoretech/airbroke/blob/main/docker-compose.yml"
    click DeployMake "https://github.com/icoretech/airbroke/tree/main/Makefile"
    click DeployGitHub "https://github.com/icoretech/airbroke/tree/main/.github/workflows"
```
