# voidagency/vactory_nextjs architecture

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

- Interactive diagram: https://gitdiagram.com/voidagency/vactory_nextjs
- Repository: https://github.com/voidagency/vactory_nextjs

## Overview

##### Project Type & Purpose
- Type: Monorepo housing multiple Next.js applications, shared packages, documentation site, and CI/CD/deployment scripts.
- Purpose:
– Provide a starter Next.js app (apps/starter) with built-in auth & API routes.
– Host a production site (apps/capital-azur) that uses shared UI and content-type packages.
– Offer a Storybook playground (apps/playground) for UI component development & testing.
– Serve a Docusaurus docs site (apps/docs).
– Publish a suite of reusable NPM packages under packages/ (ui kit, Next.js framework extensions, CMS integrations).
– Containerize via Docker and deploy via Capistrano.

##### File Structure
- Root level: lerna.json & turbo.json (monorepo manager), Dockerfile & docker-compose.yml, Capistrano folder (deploy scripts), global configs (tsconfig.json, .eslintrc.json, etc.).
- apps/: four Next.js-based apps—starter, capital-azur, playground, docs—each with its own pages/, components/, styles/, and build configs.
- packages/:
– ui: themed React components + Storybook config.
– next: Next.js utilities (i18n, proxies, SSR/SSG helpers).
– next-banners, next-blocks, next-news, next-page, next-paragraphs, next-user: modular “plugins” for content types, CMS fetchers, auth flows.
– headlessui: patched fork of HeadlessUI.
- Capistrano/: deployment recipes for staging & production.
- Scripts/: detection of unused code, monorepo helpers.

##### Key Insights from README
- Docker multi-stage build targets: runner_app (starter), runner_ui (storybook), runner_docs (docusaurus).
- Capistrano commands to deploy apps/starter to remote servers using SSH keys.
- No built-in backend database—external CMS and auth providers via next-user.

##### Main Components
A. Developer Environment & Monorepo
– Editor/IDE
– Git & Bitbucket Repo
– Lerna/Turbo (monorepo orchestration)
B. Codebase Modules
– apps/starter (Next.js SSR/SSG + API routes)
– apps/capital-azur (production site)
– apps/playground (Storybook + Next.js preview)
– apps/docs (Docusaurus docs site)
– packages/ui (React component library + themes)
– packages/next & other plugins (CMS & auth integrations)
C. Build & Packaging
– Docker daemon (multi-stage builds)
– docker-compose (local dev orchestration)
– Git push → CI triggers Lerna/Turbo, Docker build, artifact publish
E. Container Registry (if used)
F. Deployment
– Capistrano invoking SSH to staging/production servers
– Docker run containers (runner_app, runner_ui, runner_docs)
G. Runtime & External Services
– External Headless CMS APIs (used by next-news, next-blocks)
– Auth provider or custom next-user endpoints
– CDN / Static asset hosting (public/ folder)

##### Architectural Patterns
- Monorepo for code sharing
- Modular plugin architecture (each packages/next-* is independent)
- Multi-stage container images for development vs. production
- Server-side rendering and static site generation via Next.js
- Storybook as isolated component playground

##### Technologies & Frameworks
- Node.js & Next.js
- React (packages/ui)
- Docusaurus (apps/docs)
- Storybook (apps/playground + packages/ui)
- Tailwind CSS (present throughout apps)
- Lerna/Turbo (monorepo)
- Docker / docker-compose
- Capistrano / SSH deployment
- External CMS (e.g., Drupal) & Auth services

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Environment
    DevEnv["Developer Environment\nIDE / Editor"]:::external
    Git["Git Repository\n(Bitbucket)"]:::external
    DevEnv -->|commits code| Git

    %% Monorepo Orchestration
    Monorepo["Monorepo Orchestration\n(Lerna/Turbo)"]:::build
    Git -->|push| Monorepo
    click Monorepo "https://github.com/voidagency/vactory_nextjs/blob/main/lerna.json"

    %% Codebase Modules
    subgraph "Applications" 
        direction TB
        Starter["Starter App\n(apps/starter)"]:::code
        CapitalAzur["Capital-Azur App\n(apps/capital-azur)"]:::code
        Playground["Storybook Playground\n(apps/playground)"]:::code
        Docs["Documentation Site\n(apps/docs)"]:::code
    end
    click Starter "https://github.com/voidagency/vactory_nextjs/tree/main/apps/starter/"
    click CapitalAzur "https://github.com/voidagency/vactory_nextjs/tree/main/apps/capital-azur/"
    click Playground "https://github.com/voidagency/vactory_nextjs/tree/main/apps/playground/"
    click Docs "https://github.com/voidagency/vactory_nextjs/tree/main/apps/docs/"

    subgraph "Packages" 
        direction TB
        UI["UI Library\n(packages/ui)"]:::code
        NextExt["Next.js Extensions\n(packages/next)"]:::code
        HeadlessUI["HeadlessUI Fork\n(packages/headlessui)"]:::code
        subgraph "CMS & Content Plugins"
            direction TB
            Banners["next-banners\n(packages/next-banners)"]:::code
            Blocks["next-blocks\n(packages/next-blocks)"]:::code
            News["next-news\n(packages/next-news)"]:::code
            Page["next-page\n(packages/next-page)"]:::code
            Paragraphs["next-paragraphs\n(packages/next-paragraphs)"]:::code
        end
        NextUser["Auth & User Flows\n(packages/next-user)"]:::code
    end
    click UI "https://github.com/voidagency/vactory_nextjs/tree/main/packages/ui/"
    click NextExt "https://github.com/voidagency/vactory_nextjs/tree/main/packages/next/"
    click HeadlessUI "https://github.com/voidagency/vactory_nextjs/tree/main/packages/headlessui/"
    click Banners "https://github.com/voidagency/vactory_nextjs/tree/main/packages/next-banners/"
    click Blocks "https://github.com/voidagency/vactory_nextjs/tree/main/packages/next-blocks/"
    click News "https://github.com/voidagency/vactory_nextjs/tree/main/packages/next-news/"
    click Page "https://github.com/voidagency/vactory_nextjs/tree/main/packages/next-page/"
    click Paragraphs "https://github.com/voidagency/vactory_nextjs/tree/main/packages/next-paragraphs/"
    click NextUser "https://github.com/voidagency/vactory_nextjs/tree/main/packages/next-user/"

    %% Global Configs & Scripts
    Configs["Global Configs\n(tsconfig.json,\n.eslintrc.json,\n.prettierrc.json)"]:::build
    Scripts["Utility Scripts\n(scripts/detect-unused.js)"]:::build
    click Scripts "https://github.com/voidagency/vactory_nextjs/blob/main/scripts/detect-unused.js"

    %% Build & CI/CD
    Docker["Docker Build & Local Dev\n(Dockerfile,\ndocker-compose.yml)"]:::build
    click Docker "https://github.com/voidagency/vactory_nextjs/tree/main/Dockerfile"
    CICD["CI/CD Workflows\n(.warp/workflows/generate_ui_component.yaml)"]:::build
    click CICD "https://github.com/voidagency/vactory_nextjs/blob/main/.warp/workflows/generate_ui_component.yaml"

    Monorepo -->|installs & links| Starter
    Monorepo --> CapitalAzur
    Monorepo --> Playground
    Monorepo --> Docs
    Monorepo --> UI
    Monorepo --> NextExt
    Monorepo --> HeadlessUI
    Monorepo --> Banners
    Monorepo --> Blocks
    Monorepo --> News
    Monorepo --> Page
    Monorepo --> Paragraphs
    Monorepo --> NextUser
    Monorepo --> Configs
    Monorepo --> Scripts

    Starter -->|imports| UI
    Starter --> NextExt
    Starter --> Banners
    Starter --> Blocks
    Starter --> News
    Starter --> Page
    Starter --> Paragraphs
    Starter --> NextUser

    CapitalAzur --> UI
    CapitalAzur --> NextExt
    CapitalAzur --> News
    CapitalAzur --> Page
    CapitalAzur --> Paragraphs

    Playground --> UI
    Playground --> NextExt

    Docs --> UI

    Monorepo --> Docker
    Monorepo --> CICD

    %% Deployment Orchestration
    Capistrano["Deployment Orchestration\n(capistrano/)"]:::deploy
    click Capistrano "https://github.com/voidagency/vactory_nextjs/tree/main/capistrano/"

    CICD -->|triggers build| Docker
    Docker -->|push images| Registry["Container Registry"]:::deploy
    Registry -->|stores images| Servers["Staging/Production Servers"]:::deploy
    Capistrano -->|SSH deploy| Servers

    %% Runtime & External Services
    subgraph "External Services"
        direction TB
        CMS["External Headless CMS APIs"]:::external
        Auth["Auth Provider / next-user endpoints"]:::external
        CDN["CDN / Static Asset Hosting"]:::external
    end

    Starter -->|runtime fetch| CMS
    Starter -->|auth calls| Auth
    CapitalAzur --> CMS
    CapitalAzur --> Auth
    Starter --> CDN
    CapitalAzur --> CDN

    %% Connections from Dev to Deployment
    DevEnv -->|local dev| Docker
    DevEnv -->|run tests| CICD

    %% Styles
    classDef code fill:#e0f7fa,stroke:#006064,color:#006064;
    classDef build fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32;
    classDef deploy fill:#fff3e0,stroke:#ef6c00,color:#ef6c00;
    classDef external fill:#f3e5f5,stroke:#6a1b9a,color:#6a1b9a;
```
