# spear-ai/citizen architecture

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

- Interactive diagram: https://gitdiagram.com/spear-ai/citizen
- Repository: https://github.com/spear-ai/citizen

## Overview

##### Main Components
- Monorepo Management & Build System – Represented by the top-level folders (packages directory, turbo.json, yarn configuration such as .yarn/… and yarnrc.yml). This is your central hub and build orchestration system.
- Developer Tooling Integrations – This includes:
– Git Hooks (managed through .husky with commit-msg and pre-commit scripts).
– CI/CD integration (under .github with workflows like check.yaml and release.yaml).
– Shared configurations (code formatting, linting, commit message rules, versioning rules).
- Individual Configuration Packages – Each package in the “packages” folder is a module that encapsulates a particular standard or configuration:
– Code Commitment: (packages/code-commitment)
– Commitlint Config: (packages/commitlint-config)
– ESLint Config: (packages/eslint-config)
– npm-package-json-lint Config: (packages/npm-package-json-lint-config)
– Prettier Config: (packages/prettier-config)
– Pulumi Policy Pack: (packages/pulumi-policy-pack)
– Ruff Config: (packages/ruff-config)
– SQLFluff Config: (packages/sqlfluff-config)
– TSConfig: (packages/tsconfig)
- Documentation & Guidelines – Shown in the docs folder and README. This contains details such as language rules and stylistic guidelines (e.g. for comments, variables, punctuation, etc.)

##### Relationships and Interactions
- The monorepo layer manages versioning, caching, and workspace resolutions across the various configuration packages. There is a clear dependency where each configuration package stands alone but is reused by external projects or local setups.
- The CI/CD pipelines in .github run tests (and lint checks) which pull in the configurations from some of these packages.
- Git hooks, facilitated with Husky, are integrated at the repository root to automatically enforce and check commit message formatting, style rules, and other quality standards—as defined by the commitlint and code-commitment packages.
- The documentation provides a “living” style guide that ties all these components together regarding coding practices.

##### Architectural Patterns & Design Principles
- Reuse & Separation of Concerns: Different packages serve different purposes (linting, formatting, commit standards, etc.), but they are unified by a common goal.
- CI/CD and Local Hooks: Clearly indicate that changes in any package trigger tests (via GitHub Actions) and local checks (via Husky hooks).

##### Relevant Technologies/Frameworks/Libraries
- Yarn (with its caching and Plug’n’Play) and Turbo (turbo.json) for workspace orchestration.
- GitHub Actions (workflows in .github) for automated tests and releases.
- Husky for pre-commit and commit-msg hooks.
- ESLint, Prettier, Commitlint, npm-package-json-lint, and language-specific tools (ruff for Python, sqlfluff for SQL, TSConfig for TypeScript) as the core libraries driving individual rules.

##### Elements
- Each component should have a clear label:
– “Monorepo Manager” (including Yarn, Turbo)
– “Configuration Packages” (each package: Code Commitment, Commitlint, ESLint, npm-package-json-lint, Prettier, etc.)
– “Developer Environment” (VSCode, local Git, Husky)
– “CI/CD Pipeline” (GitHub Actions, workflows)
– “Documentation & Guidelines” (docs folder, README)
– How configuration packages are consumed by local development tools,
– How Git hooks are triggered on commits and interact with the commit standards packages,
– And how the CI pipeline validates the repository by pulling in these configurations.
– Rule/guideline modules (perhaps a rectangle with a notch),
– Infrastructure components (rounded rectangles or clouds for CI/CD),

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Infrastructure Subgraph
    subgraph "Infrastructure"
        monorepo["Monorepo Manager"]:::infra
        gitHooks["Git Hooks"]:::infra
        cicd["CI/CD Pipeline"]:::infra
    end

    %% Configuration Packages Subgraph
    subgraph "Configuration Packages"
        codeCommit["Code Commitment"]:::config
        commitlint["Commitlint Config"]:::config
        eslint["ESLint Config"]:::config
        npmLint["npm-package-json-lint Config"]:::config
        prettier["Prettier Config"]:::config
        pulumi["Pulumi Policy Pack"]:::config
        ruff["Ruff Config"]:::config
        sqlfluff["SQLFluff Config"]:::config
        tsconfig["TSConfig"]:::config
    end

    %% Aggregation Interface for Configurations
    configInterface["Config Interface"]:::interface

    %% Other Nodes
    developer["Developer Environment (VSCode,Git)"]:::dev
    docs["Documentation & Guidelines"]:::doc

    %% Relationships from Infrastructure to Configuration Packages
    monorepo -->|"builds"| codeCommit
    monorepo -->|"builds"| commitlint
    monorepo -->|"builds"| eslint
    monorepo -->|"builds"| npmLint
    monorepo -->|"builds"| prettier
    monorepo -->|"builds"| pulumi
    monorepo -->|"builds"| ruff
    monorepo -->|"builds"| sqlfluff
    monorepo -->|"builds"| tsconfig

    gitHooks -->|"enforces"| codeCommit
    gitHooks -->|"enforces"| commitlint

    %% Aggregation from Configuration Packages to Config Interface
    commitlint -->|"aggregates"| configInterface

    %% Consumption by Developer Environment and Validation by CI/CD
    configInterface -->|"consumed_by"| developer
    configInterface -->|"validated_by"| cicd

    %% Documentation guides Developer Environment
    docs -->|"guides"| developer

    %% Class Definitions for Colors
    classDef infra fill:#FFDD57,stroke:#333,stroke-width:2px;
    classDef config fill:#A2D9CE,stroke:#333,stroke-width:2px;
    classDef interface fill:#F5B7B1,stroke:#333,stroke-width:2px;
    classDef dev fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef doc fill:#F9E79F,stroke:#333,stroke-width:2px;

    %% Click Events for Infrastructure
    click monorepo "https://github.com/spear-ai/citizen/tree/main/packages"
    click monorepo "https://github.com/spear-ai/citizen/blob/main/turbo.json"
    click monorepo "https://github.com/spear-ai/citizen/blob/main/.yarn"
    click monorepo "https://github.com/spear-ai/citizen/blob/main/yarnrc.yml"
    click gitHooks "https://github.com/spear-ai/citizen/blob/main/.husky"
    click cicd "https://github.com/spear-ai/citizen/blob/main/.github"

    %% Click Events for Documentation
    click docs "https://github.com/spear-ai/citizen/blob/main/README.md"
    click docs "https://github.com/spear-ai/citizen/tree/main/docs"
    click docs "https://github.com/spear-ai/citizen/tree/main/docs/software-stack"

    %% Click Events for Configuration Packages
    click codeCommit "https://github.com/spear-ai/citizen/tree/main/packages/code-commitment"
    click commitlint "https://github.com/spear-ai/citizen/tree/main/packages/commitlint-config"
    click eslint "https://github.com/spear-ai/citizen/tree/main/packages/eslint-config"
    click npmLint "https://github.com/spear-ai/citizen/tree/main/packages/npm-package-json-lint-config"
    click prettier "https://github.com/spear-ai/citizen/tree/main/packages/prettier-config"
    click pulumi "https://github.com/spear-ai/citizen/tree/main/packages/pulumi-policy-pack"
    click ruff "https://github.com/spear-ai/citizen/tree/main/packages/ruff-config"
    click sqlfluff "https://github.com/spear-ai/citizen/tree/main/packages/sqlfluff-config"
    click tsconfig "https://github.com/spear-ai/citizen/tree/main/packages/tsconfig"
```
