# toastboy/next-www-toastboy architecture

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

- Interactive diagram: https://gitdiagram.com/toastboy/next-www-toastboy
- Repository: https://github.com/toastboy/next-www-toastboy

## Overview

##### Project type and purpose
- This is a full-stack, server-centric Next.js 13 application (“app” directory) backed by a MySQL database via Prisma ORM.
- Styled with Tailwind CSS.
- Infrastructure‐as‐code in `terraform/` targets Azure, plus local development defined in `docker-compose.yml`.
- Automated testing with Jest (unit tests), Playwright (E2E), and CI/CD via GitHub Actions.

##### File structure
- Frontend: `src/components/` (React UI), `src/app/*/page.tsx` (Next.js Server & Client Components).
- API layer: `src/app/api/footy/.../route.ts` (Next.js Route Handlers) + `src/actions` (server‐side business actions).
- Business logic & data access: `src/services/` (domain services), `src/lib/` (utilities, API client wrappers, auth, config).
- Data layer: `prisma/` (schema.prisma, migrations, generated client).
- Infrastructure: `terraform/` (Azure MySQL, resource groups, outputs), `docker-compose.yml` (local MySQL, Next.js).
- Testing: `tests/` for unit, `e2e/` for end-to-end using Playwright.
- CI/CD: `.github/workflows/*` (lint, test, terraform plan/apply).

##### README for additional insights
- Azure + MySQL sample adapted to own domain (“footy” data).
- Uses Prisma introspection to generate schema from live DB.
- Local dev expects `DATABASE_URL` environment variable.
- Run with `npm run dev` → localhost:3000.

a. Main components
- Browser (Next.js front-end pages & client components).
- Next.js server layer (React Server Components, Route Handlers / API).
- Business services layer (`src/services`, `src/actions`).
- Prisma Client (generated client communicates via SQL).
- MySQL database (Azure-hosted in production, Docker container locally).
- Infrastructure as Code (Terraform → Azure resources).
- CI/CD pipelines (GitHub Actions).
- Observability (Sentry, instrumentation).
- Test runners (Jest, Playwright) as separate logical components.

b. Relationships and interactions
- Browser ⟷ Next.js Server Components (HTTP/SSR).
- Browser → API Route Handlers (fetch/XHR for dynamic data).
- Route Handlers → Services (internal method calls).
- Services → Prisma Client → MySQL (SQL queries over TCP).
- CI/CD workflows trigger Terraform plan/apply and deploy Next.js to hosting.
- Instrumentation calls from both client & server to Sentry.
- Playwright interacts with Browser → Server in test environment.
- Docker Compose connects Next.js container to MySQL container in dev.

c. Architectural patterns & design principles
- Monolithic web app split into Presentation (React), Application (Route Handlers & Services), Data (Prisma + MySQL).
- Serverless‐style functions (Next.js Route Handlers deployed as lambdas or Azure Functions).
- Infrastructure as Code (Terraform).
- Automated CI/CD.
- Test pyramid: unit (Jest), integration (Jest API tests), E2E (Playwright).

d. Key technologies
- Next.js 13 App Router (React server/client components).
- Tailwind CSS.
- Prisma ORM with generated client.
- MySQL (prod on Azure, dev via Docker).
- Terraform (Azure provider).
- GitHub Actions.
- Jest, Playwright.
- Sentry (error monitoring).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Browser["Browser"]:::client
        subgraph "Frontend"
            Components["React UI & Components"]:::client
            Pages["Next.js App Router Pages"]:::client
        end
    end

    %% Server Layer
    subgraph "Server Layer"
        subgraph "Next.js Server"
            ServerApp["App Router & API Route Handlers"]:::compute
        end
        subgraph "Business Logic"
            Actions["Server-side Actions"]:::compute
            Services["Domain Services"]:::compute
            Lib["Utilities & Configuration"]:::compute
        end
        subgraph "ORM"
            PrismaClient["Prisma Client"]:::compute
        end
        Observability["Sentry (Observability)"]:::compute
    end

    %% Data Layer
    subgraph "Data Layer"
        MySQL["MySQL Database"]:::db
        Schema["Prisma Schema & Migrations"]:::db
    end

    %% Infrastructure & CI/CD
    Terraform["Terraform (Azure IaC)"]:::cloud
    Docker["Docker Compose (Local Dev)"]:::cloud
    CICD["GitHub Actions (CI/CD)"]:::ci
    E2E["Playwright E2E Tests"]:::ci
    Tests["Jest Unit & Integration Tests"]:::ci
    NextConfig["Next.js Configuration"]:::compute
    SentryEdge["sentry.edge.config.ts"]:::compute
    SentryServer["sentry.server.config.ts"]:::compute

    %% Connections
    Browser -->|"SSR/HTTP"| ServerApp
    Browser -->|"XHR/Fetch"| ServerApp
    ServerApp -->|calls| Actions
    Actions -->|uses| Services
    Services -->|queries| PrismaClient
    PrismaClient -->|SQL over TCP| MySQL
    Browser -->|captures errors| Observability
    ServerApp -->|captures errors| Observability

    CICD -->|deploy & terraform| Terraform
    CICD -->|deploy Next.js| ServerApp
    Terraform -->|provisions| MySQL:::cloud
    Docker -.->|local connect| MySQL
    Docker -.->|local run| ServerApp

    E2E -->|automates| Browser
    Tests -->|unit & integration| Services
    Tests -->|unit| Lib

    %% Click Events
    click Components "https://github.com/toastboy/next-www-toastboy/tree/main/src/components/"
    click Pages "https://github.com/toastboy/next-www-toastboy/blob/main/src/app/page.tsx"
    click ServerApp "https://github.com/toastboy/next-www-toastboy/tree/main/src/app/api/footy/"
    click Actions "https://github.com/toastboy/next-www-toastboy/tree/main/src/actions/"
    click Services "https://github.com/toastboy/next-www-toastboy/tree/main/src/services/"
    click Lib "https://github.com/toastboy/next-www-toastboy/tree/main/src/lib/"
    click PrismaClient "https://github.com/toastboy/next-www-toastboy/tree/main/prisma/generated/prisma/client/"
    click Schema "https://github.com/toastboy/next-www-toastboy/blob/main/prisma/schema.prisma"
    click Docker "https://github.com/toastboy/next-www-toastboy/blob/main/docker-compose.yml"
    click Terraform "https://github.com/toastboy/next-www-toastboy/tree/main/terraform/"
    click CICD "https://github.com/toastboy/next-www-toastboy/tree/main/.github/workflows/"
    click E2E "https://github.com/toastboy/next-www-toastboy/tree/main/e2e/"
    click Tests "https://github.com/toastboy/next-www-toastboy/tree/main/tests/"
    click SentryEdge "https://github.com/toastboy/next-www-toastboy/blob/main/sentry.edge.config.ts"
    click SentryServer "https://github.com/toastboy/next-www-toastboy/blob/main/sentry.server.config.ts"
    click NextConfig "https://github.com/toastboy/next-www-toastboy/blob/main/next.config.mjs"

    %% Styles
    classDef client fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef compute fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef db fill:#ffffcc,stroke:#333,stroke-width:1px
    classDef cloud fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef ci fill:#ffe5cc,stroke:#333,stroke-width:1px
    class Docker dashed
```
