How spear-ai/citizen works
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),