# blazity/next-enterprise architecture

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

- Interactive diagram: https://gitdiagram.com/blazity/next-enterprise
- Repository: https://github.com/blazity/next-enterprise

## Overview

##### Project Type and Purpose
- This is a full-stack, production-ready Next.js enterprise boilerplate. It provides a streamlined foundation for building performant, scalable React applications with integrated infrastructure, testing, and deployment pipelines.

##### Main Components
a. Frontend (Next.js App Directory)
- app/layout.tsx & app/page.tsx: Root layout and page definitions
- app/api/health/route.ts: Built-in health-check API endpoint
- components/: Reusable UI primitives (Button, Tooltip, etc.) with Storybook integration
- styles/tailwind.css: Global Tailwind CSS configuration
b. Rendering & Data Fetching
- SSR/SSG layers provided by Next.js
- Bundle analysis & performance tuning via next.config.ts and bundle-analyzer
c. Infrastructure & Deployment
- Vercel (default) or Terraform IaC for AWS (ECS, ECR, ALB, S3/CloudFront, Redis, VPC, WAF)
- Health checks compatible with Kubernetes-style probes
d. CI/CD & Automation
- GitHub Actions workflows (.github/workflows/*.yml) for linting, tests, bundle analysis, and release
- Semantic Release, Renovate bot, Conventional Commits for automated versioning
e. Testing & Quality
- Jest & React Testing Library (jest.config.js, jest.setup.js) for unit tests
- Playwright (playwright.config.ts) for E2E & acceptance tests (e2e/)
- Storybook (storybook/) for component-driven development
f. Observability
- OpenTelemetry instrumentation (instrumentation.ts) for metrics/tracing
g. Config & Utilities
- TypeScript with strict settings (tsconfig.json, next-env.d.ts, reset.d.ts)
- ESLint, Prettier (eslint.config.mjs, prettier.config.js)
- Environment management (env.mjs, T3 Env)

##### Relationships & Data Flow
- Browser clients → HTTP(S) → Next.js server (SSR/SSG)
- Next.js server → Internal API routes (app/api/health) for liveness checks
- Next.js server → External services (database/cache, e.g., Redis)
- Next.js static asset requests → S3/CloudFront or Vercel CDN
- CI triggers on git events → GitHub Actions → Tests/Lint → Bundle analysis → Deployment (Vercel or Terraform CLI)
- Instrumentation hooks → OpenTelemetry collector

##### Architectural Patterns & Principles
- App Directory pattern (Next.js 15) for co-locating UI, data fetching, and metadata
- Atomic component design (components/) with Storybook-driven development
- Infrastructure as Code (Terraform) for repeatable, version-controlled environments
- Observability by design via OpenTelemetry
- Layered CI/CD pipeline with quality gates (lint, tests, bundle size)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Frontend (UI Layer)"
        Browser["Browser Client"]:::ui
        SSR["Next.js SSR/SSG Engine"]:::ui
        Button["Button Component"]:::ui
        Tooltip["Tooltip Component"]:::ui
        Styles["tailwind.css"]:::ui
        Storybook["Storybook"]:::ui
    end

    subgraph "API & Business Logic"
        Health["Health-Check API"]:::api
    end

    subgraph "Data Stores"
        Redis[(Redis Cache)]:::infra
    end

    subgraph "Infrastructure & Deployment"
        Vercel{"Vercel CDN/Hosting"}:::infra
        Terraform{"Terraform IaC (AWS)"}:::infra
        AWSinfra["AWS Services (ECS, ECR, S3/CloudFront, ALB, VPC, WAF)"]:::infra
    end

    subgraph "CI/CD & Automation"
        GitHub["GitHub Repo"]:::ci
        LintTests["Actions: Lint & Tests"]:::ci
        BundleCI["Actions: Bundle Analysis"]:::ci
        E2E["Actions: E2E Testing"]:::ci
        Release["Release (Semantic)"]:::ci
    end

    subgraph "Observability"
        Instr["OpenTelemetry Instrumentation"]:::obs
        Collector["OTel Collector"]:::obs
    end

    Browser -->|"HTTPS"| SSR
    SSR -->|"Internal API"| Health
    SSR -->|"Redis"| Redis
    SSR -->|"Static Assets"| Vercel
    SSR -->|"instrument"| Instr

    GitHub -->|"push/PR"| LintTests
    LintTests -->|"after lint/tests"| BundleCI
    BundleCI -->|"after analysis"| E2E
    E2E -->|"on success"| Release
    Release -->|"deploy to Vercel"| Vercel
    Release -->|"terraform apply"| Terraform
    Terraform -->|"provisions"| AWSinfra

    Instr -->|"metrics/traces"| Collector

    click SSR "https://github.com/blazity/next-enterprise/blob/main/app/layout.tsx"
    click Health "https://github.com/blazity/next-enterprise/blob/main/app/api/health/route.ts"
    click Button "https://github.com/blazity/next-enterprise/blob/main/components/Button/Button.tsx"
    click Tooltip "https://github.com/blazity/next-enterprise/blob/main/components/Tooltip/Tooltip.tsx"
    click Styles "https://github.com/blazity/next-enterprise/blob/main/styles/tailwind.css"
    click BundleCI "https://github.com/blazity/next-enterprise/blob/main/.github/workflows/nextjs_bundle_analysis.yml"
    click LintTests "https://github.com/blazity/next-enterprise/blob/main/.github/workflows/check.yml"
    click E2E "https://github.com/blazity/next-enterprise/blob/main/.github/workflows/playwright.yml"
    click Instr "https://github.com/blazity/next-enterprise/blob/main/instrumentation.ts"

    classDef ui fill:#cfe2ff,stroke:#0d6efd,color:#0d6efd;
    classDef api fill:#d1e7dd,stroke:#198754,color:#198754;
    classDef infra fill:#fff3cd,stroke:#ffc107,color:#856404;
    classDef ci fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef obs fill:#cff4fc,stroke:#0dcaf0,color:#0a99c7;
```
