# sixfeetup/scaf architecture

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

- Interactive diagram: https://gitdiagram.com/sixfeetup/scaf
- Repository: https://github.com/sixfeetup/scaf

## Overview

##### Major Components
- Template Manager CLI (Scaf’s executable and scripts, e.g., “scaf”, “install.sh”, “test-scaf.sh”). This is the core component that interacts with the user.
- Template Repository Connector: Represents how Scaf accesses external templates on GitHub repositories (e.g., Six Feet Up Full Stack Template, AWS Lambda App Template).
- Copier Engine Integration: Display that Scaf leverages Copier (the templating engine) to install and update the templates.
- Project Structure Generator: Illustrate the output of a new project, which includes numerous components such as:
– Django backend and optional Celery
– Next.js frontend (with Strawberry GraphQL and Apollo Client, or a REST API alternative in the future)
– Kubernetes manifests organized into three Kustomize layers (dev, sandbox, production)
– Supporting infrastructure components: Postgres (local) and CloudNativePG (production), Redis, Mailhog, Traefik, ArgoCD, Certmanager (for certificates and ingress), Kube Prometheus Stack, Grafana Loki, and even integration with Sentry.
- Infrastructure Automation and CI/CD:
– GitHub workflows (as seen in the .github folder) for semantic-release and testing
– Terraform and AWS integration (and the supporting scripts/documentation)
- Development Environment Setup:
– Nix Flake configuration (flake.nix and flake.lock) along with direnv (.envrc)
– Various configuration and dependency files (requirements.in/requirements.txt, package.json) which ensure reproducibility.

##### Out Relationships and Data Flow
- Link the “Template Repository Connector” to both the “CLI” and “Copier” components, showing that Scaf pulls templates from remote GitHub repositories.
- “Generated Project Structure” with “Kubernetes & Infrastructure Components” showing that the new project includes Kubernetes manifests (Kustomize layers), Terraform scripts, and CI/CD pipelines.
- How “Development Environment Setup” (Nix Flake, direnv) wraps around Scaf to ensure consistency in the developer’s environment.

##### Architectural Patterns and Design Principles
- A modular and extensible architecture — Scaf separates the template management (via Copier) from the actual generated project structure.
- Notice the clear separation of concerns: the CLI drives the application logic, then delegates the actual scaffolding to an underlying templating tool.
- Underline the integration of infrastructure-as-code (with Kubernetes manifests in multiple layers, Terraform, and AWS integration), which is central to its blueprint for production deployments.
- Mention that reproducibility and consistency are enforced through the use of Nix Flakes and direnv, which ensure a consistent development environment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    User["User/Developer"]:::userClass

    %% Template Manager CLI Subgraph
    subgraph "Template Manager CLI"
        TMCLI_scaf["Executable: scaf"]:::cliClass
        TMCLI_install["Installation Script: install.sh"]:::cliClass
        TMCLI_test["Testing Script: test-scaf.sh"]:::cliClass
    end

    %% Copier Engine Integration and Template Repository Connector
    Copier["Copier Engine Integration"]:::copierClass
    RepoConnector["Template Repository Connector"]:::repoClass

    %% Generated Project Structure Subgraph
    subgraph "Generated Project Structure"
        Django["Django Backend (with optional Celery)"]:::projectClass
        Nextjs["Next.js Frontend"]:::projectClass
        K8sManifests["Kubernetes Manifests (Kustomize: dev, sandbox, production)"]:::projectClass
        subgraph "Supporting Infrastructure"
            Database["Postgres / CloudNativePG"]:::infraClass
            Redis["Redis"]:::infraClass
            Mailhog["Mailhog"]:::infraClass
            Traefik["Traefik"]:::infraClass
            ArgoCD["ArgoCD"]:::infraClass
            Certmanager["Certmanager"]:::infraClass
            KubeProm["Kube Prometheus Stack"]:::infraClass
            GrafanaLoki["Grafana Loki"]:::infraClass
            Sentry["Sentry"]:::infraClass
        end
    end

    %% Infrastructure Automation and CI/CD Subgraph
    subgraph "Infrastructure Automation & CI/CD"
        GH_Workflows["GitHub Workflows"]:::infraClass
        GH_semanticPR["semantic-pull-request.yaml"]:::infraClass
        GH_semanticRelease["semantic-release.yaml"]:::infraClass
        GH_setupProject["setup-project.yaml"]:::infraClass
        Terraform["Terraform & AWS Integration"]:::infraClass
    end

    %% Development Environment Setup Subgraph
    subgraph "Development Environment Setup"
        flake_nix["flake.nix"]:::devClass
        flake_lock["flake.lock"]:::devClass
        EnvRC[".envrc"]:::devClass
        package_json["package.json"]:::devClass
        requirements_in["requirements.in"]:::devClass
        requirements_txt["requirements.txt"]:::devClass
    end

    %% Connections
    User -->|"invokes"| TMCLI_scaf
    User -->|"sets up environment"| EnvRC

    %% Template Manager CLI connections
    TMCLI_scaf -->|"calls"| Copier
    TMCLI_scaf -->|"accesses"| RepoConnector
    TMCLI_install --- TMCLI_scaf
    TMCLI_test --- TMCLI_scaf

    %% Copier and Repository connections
    Copier -->|"fetches templates"| RepoConnector
    Copier -->|"generates"| Django

    %% Generated Project Structure internal flow
    Django -->|"integrates with"| Nextjs
    Nextjs -->|"bundled with"| K8sManifests
    K8sManifests -->|"deploys"| Database
    K8sManifests -->|"deploys"| Redis
    K8sManifests -->|"deploys"| Mailhog
    K8sManifests -->|"deploys"| Traefik
    K8sManifests -->|"deploys"| ArgoCD
    K8sManifests -->|"deploys"| Certmanager
    K8sManifests -->|"monitored by"| KubeProm
    K8sManifests -->|"logs sent to"| GrafanaLoki
    K8sManifests -->|"error tracking"| Sentry

    %% Connect Generated Project Structure to Infrastructure Automation
    K8sManifests -->|"integrates with"| GH_Workflows
    Terraform -->|"provisions"| K8sManifests

    %% Connect Generated Project Structure to Development Environment Setup
    Django -->|"developed with"| flake_nix
    Nextjs -->|"developed with"| package_json

    %% Style Classes
    classDef userClass fill:#fcf3cf,stroke:#333,stroke-width:2px;
    classDef cliClass fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef copierClass fill:#e8daef,stroke:#333,stroke-width:2px;
    classDef repoClass fill:#fadbd8,stroke:#333,stroke-width:2px;
    classDef projectClass fill:#d5f5e3,stroke:#333,stroke-width:2px;
    classDef infraClass fill:#a9dfbf,stroke:#333,stroke-width:2px;
    classDef devClass fill:#aed6f1,stroke:#333,stroke-width:2px;

    %% Click Events for Template Manager CLI
    click TMCLI_scaf "https://github.com/sixfeetup/scaf/tree/dev/scaf"
    click TMCLI_install "https://github.com/sixfeetup/scaf/blob/dev/install.sh"
    click TMCLI_test "https://github.com/sixfeetup/scaf/blob/dev/test-scaf.sh"

    %% Click Events for GitHub Workflows files
    click GH_semanticPR "https://github.com/sixfeetup/scaf/blob/dev/.github/workflows/semantic-pull-request.yaml"
    click GH_semanticRelease "https://github.com/sixfeetup/scaf/blob/dev/.github/workflows/semantic-release.yaml"
    click GH_setupProject "https://github.com/sixfeetup/scaf/blob/dev/.github/workflows/setup-project.yaml"

    %% Click Events for Development Environment Setup
    click flake_nix "https://github.com/sixfeetup/scaf/blob/dev/flake.nix"
    click flake_lock "https://github.com/sixfeetup/scaf/blob/dev/flake.lock"
    click EnvRC "https://github.com/sixfeetup/scaf/blob/dev/.envrc"
    click package_json "https://github.com/sixfeetup/scaf/blob/dev/package.json"
    click requirements_in "https://github.com/sixfeetup/scaf/blob/dev/requirements.in"
    click requirements_txt "https://github.com/sixfeetup/scaf/blob/dev/requirements.txt"
```
