# artificialsenselabs/handbook-public architecture

> Architecture diagram of the GitHub repository artificialsenselabs/handbook-public, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/artificialsenselabs/handbook-public
- Repository: https://github.com/artificialsenselabs/handbook-public

## Overview

1. This repository is a **Markdown-only engineering handbook**. It has no application runtime, package build, or production deployment. The “architecture” is a documentation system organized around content folders, templates, and validation scripts.

2. The **core content layer** is the topic taxonomy: `angular/`, `nx/`, `css-scss/`, `tooling/`, `security/`, `debugging/`, `how-to/`, `snippets/`, `til/`, `prompts/`, and `principles/`. Each folder is a distinct knowledge boundary with its own purpose, and the root `README.md` acts as the entry point and navigation map.

3. The repository distinguishes between **topic docs** and **cross-cutting principles**. Topic folders answer tool- or task-specific questions, while `principles/` holds workspace-wide decision frameworks that apply across projects. This matters for diagramming because it separates “how-to knowledge” from “policy/architecture knowledge.”

4. The **template subsystem** lives in `_templates/`. It provides starting points for new notes, enforcing consistent structure across how-to, debugging, TIL, and prompt documents. New content is typically created by copying a template into the appropriate topic folder rather than generated by code.

5. The **contribution workflow** is editorial, not programmatic: authors add or update Markdown files, choose the right folder, follow filename conventions, and rely on editor search instead of a manual index. `CONTRIBUTING.md` defines the process and conventions for note creation and link hygiene.

6. The **automation subsystem** is in `scripts/`. These are repository-maintenance tools, not product features. They support tasks like bootstrapping the workspace, checking internal links, checking external links, and detecting repo-list drift. The scripts are the main operational glue between the handbook content and CI checks.

7. The **CI/validation boundary** is GitHub Actions under `.github/workflows/`. The workflows run link checks and repository drift checks, ensuring docs stay navigable and references remain valid. The repo is therefore validated primarily by static analysis of links and references, not by compilation or tests.

8. There is a strong **public/private boundary** in the content model. The handbook is public, while references to internal workspace repos are intentionally de-linked plain text marked as internal. This prevents leaking private repository URLs while still allowing the docs to describe workspace concepts.

9. The repository also contains a **standards and conventions layer** under `tooling/`, `security/`, and `principles/`. These sections document shared practices like GitHub token handling, conventional commits, semantic versioning, pnpm behavior, and theming/build-vs-buy decisions. In an architecture diagram, these are governance and operating-model inputs to the rest of the handbook.

10. The main data flow is simple: **author writes Markdown → templates/conventions shape the note → scripts and GitHub Actions validate links and repo consistency → readers navigate via folder structure and search**. There is no content rendering pipeline beyond Markdown display in GitHub and editor-based search.

11. The root README and folder READMEs function as the **navigation and discovery layer**. They give the repository its structure without maintaining a separate index, which keeps the system low-maintenance and avoids stale metadata.

12. Overall, this repo is best modeled as a **documentation knowledge base with light automation**: content folders as the primary domains, templates as scaffolding, scripts as maintenance utilities, and CI as integrity enforcement.

Main entry points: [`README.md`](https://github.com/artificialsenselabs/handbook-public/blob/main/README.md) (README), [`_templates`](https://github.com/artificialsenselabs/handbook-public/tree/main/_templates) (Templates), [`scripts`](https://github.com/artificialsenselabs/handbook-public/tree/main/scripts) (Scripts), [`CONTRIBUTING.md`](https://github.com/artificialsenselabs/handbook-public/blob/main/CONTRIBUTING.md) (Contributing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_navigation["Navigation"]
  node_readme["README<br/>entrypoint<br/>[README.md]"]
  node_contributing["Contributing<br/>editorial guide<br/>[CONTRIBUTING.md]"]
end

subgraph group_content["Content taxonomy"]
  node_angular["Angular<br/>topic area<br/>[README.md]"]
  node_nx["Nx<br/>topic area<br/>[README.md]"]
  node_cssscss["CSS/SCSS<br/>topic area<br/>[README.md]"]
  node_debugging["Debugging<br/>topic area<br/>[README.md]"]
  node_howto["How-to<br/>procedural notes<br/>[README.md]"]
  node_prompts["Prompts<br/>prompt library<br/>[README.md]"]
  node_snippets["Snippets<br/>reference notes<br/>[README.md]"]
  node_til["TIL<br/>micro-notes<br/>[README.md]"]
end

subgraph group_scaffolding["Scaffolding"]
  node_templates["Templates"]
end

subgraph group_automation["Automation"]
  node_scripts["Scripts<br/>maintenance tools"]
  node_workflows["Workflows<br/>CI checks<br/>[workflows]"]
  node_checklinks["Link check<br/>validation script<br/>[check-links.py]"]
  node_checkexternal["External links<br/>validation script"]
  node_driftcheck["Drift check<br/>validation script"]
  node_linkwf["Link CI<br/>workflow<br/>[link-check.yml]"]
  node_externallinkwf["External CI<br/>workflow"]
  node_driftwf["Drift CI<br/>workflow"]
end

subgraph group_governance["Governance"]
  node_principles["Principles<br/>decision framework<br/>[README.md]"]
  node_tooling["Tooling<br/>standards<br/>[README.md]"]
  node_security["Security<br/>operating guidance<br/>[README.md]"]
end

node_readme -->|"routes to"| node_angular
node_readme -->|"routes to"| node_nx
node_readme -->|"routes to"| node_cssscss
node_readme -->|"routes to"| node_debugging
node_readme -->|"routes to"| node_howto
node_readme -->|"routes to"| node_prompts
node_readme -->|"routes to"| node_snippets
node_readme -->|"routes to"| node_til
node_readme -->|"routes to"| node_principles
node_readme -->|"routes to"| node_tooling
node_readme -->|"routes to"| node_security
node_readme -->|"points to"| node_contributing
node_contributing -->|"uses"| node_templates
node_contributing -->|"relies on"| node_scripts
node_templates -->|"scaffolds"| node_howto
node_templates -->|"scaffolds"| node_debugging
node_templates -->|"scaffolds"| node_til
node_templates -->|"scaffolds"| node_prompts
node_principles -->|"informs"| node_tooling
node_principles -->|"informs"| node_security
node_scripts -->|"contains"| node_checklinks
node_scripts -->|"contains"| node_checkexternal
node_scripts -->|"contains"| node_driftcheck
node_checklinks -->|"runs in"| node_linkwf
node_checkexternal -->|"runs in"| node_externallinkwf
node_driftcheck -->|"runs in"| node_driftwf
node_linkwf -->|"protects"| node_readme
node_externallinkwf -->|"protects"| node_readme
node_driftwf -->|"protects"| node_readme
node_tooling -->|"constrains"| node_templates

click node_readme "https://github.com/artificialsenselabs/handbook-public/blob/main/README.md"
click node_contributing "https://github.com/artificialsenselabs/handbook-public/blob/main/CONTRIBUTING.md"
click node_templates "https://github.com/artificialsenselabs/handbook-public/tree/main/_templates"
click node_scripts "https://github.com/artificialsenselabs/handbook-public/tree/main/scripts"
click node_workflows "https://github.com/artificialsenselabs/handbook-public/blob/main/.github/workflows"
click node_angular "https://github.com/artificialsenselabs/handbook-public/blob/main/angular/README.md"
click node_nx "https://github.com/artificialsenselabs/handbook-public/blob/main/nx/README.md"
click node_cssscss "https://github.com/artificialsenselabs/handbook-public/blob/main/css-scss/README.md"
click node_debugging "https://github.com/artificialsenselabs/handbook-public/blob/main/debugging/README.md"
click node_howto "https://github.com/artificialsenselabs/handbook-public/blob/main/how-to/README.md"
click node_prompts "https://github.com/artificialsenselabs/handbook-public/blob/main/prompts/README.md"
click node_snippets "https://github.com/artificialsenselabs/handbook-public/blob/main/snippets/README.md"
click node_til "https://github.com/artificialsenselabs/handbook-public/blob/main/til/README.md"
click node_principles "https://github.com/artificialsenselabs/handbook-public/blob/main/principles/README.md"
click node_tooling "https://github.com/artificialsenselabs/handbook-public/blob/main/tooling/README.md"
click node_security "https://github.com/artificialsenselabs/handbook-public/blob/main/security/README.md"
click node_checklinks "https://github.com/artificialsenselabs/handbook-public/blob/main/scripts/check-links.py"
click node_checkexternal "https://github.com/artificialsenselabs/handbook-public/blob/main/scripts/check-external-links.py"
click node_driftcheck "https://github.com/artificialsenselabs/handbook-public/blob/main/scripts/check-repo-list-drift.sh"
click node_linkwf "https://github.com/artificialsenselabs/handbook-public/blob/main/.github/workflows/link-check.yml"
click node_externallinkwf "https://github.com/artificialsenselabs/handbook-public/blob/main/.github/workflows/external-link-check.yml"
click node_driftwf "https://github.com/artificialsenselabs/handbook-public/blob/main/.github/workflows/repo-list-drift.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_contributing toneBlue
class node_angular,node_nx,node_cssscss,node_debugging,node_howto,node_prompts,node_snippets,node_til toneAmber
class node_templates toneMint
class node_scripts,node_workflows,node_checklinks,node_checkexternal,node_driftcheck,node_linkwf,node_externallinkwf,node_driftwf toneRose
class node_principles,node_tooling,node_security toneIndigo
```

## Components

### Navigation

Entry points and editorial process

- [README](https://github.com/artificialsenselabs/handbook-public/blob/main/README.md): entrypoint · Root navigation map for the handbook · `README.md`
- [Contributing](https://github.com/artificialsenselabs/handbook-public/blob/main/CONTRIBUTING.md): editorial guide · How to add notes and maintain links · `CONTRIBUTING.md`

### Content taxonomy

Topic folders and cross-cutting handbook knowledge

- [Angular](https://github.com/artificialsenselabs/handbook-public/blob/main/angular/README.md): topic area · Angular-specific knowledge and patterns · `angular/README.md`
- [Nx](https://github.com/artificialsenselabs/handbook-public/blob/main/nx/README.md): topic area · Nx workspace knowledge · `nx/README.md`
- [CSS/SCSS](https://github.com/artificialsenselabs/handbook-public/blob/main/css-scss/README.md): topic area · Styling and stylesheet notes · `css-scss/README.md`
- [Debugging](https://github.com/artificialsenselabs/handbook-public/blob/main/debugging/README.md): topic area · Troubleshooting notes and gotchas · `debugging/README.md`
- [How-to](https://github.com/artificialsenselabs/handbook-public/blob/main/how-to/README.md): procedural notes · Task-oriented workflows and runbooks · `how-to/README.md`
- [Prompts](https://github.com/artificialsenselabs/handbook-public/blob/main/prompts/README.md): prompt library · Reusable AI task prompts · `prompts/README.md`
- [Snippets](https://github.com/artificialsenselabs/handbook-public/blob/main/snippets/README.md): reference notes · Small reusable command and config references · `snippets/README.md`
- [TIL](https://github.com/artificialsenselabs/handbook-public/blob/main/til/README.md): micro-notes · Short dated learnings and discoveries · `til/README.md`

### Scaffolding

Templates and authoring conventions

- [Templates](https://github.com/artificialsenselabs/handbook-public/tree/main/_templates): note templates · Starting points for common note types · `_templates`

### Automation

Maintenance scripts and CI validation

- [Scripts](https://github.com/artificialsenselabs/handbook-public/tree/main/scripts): maintenance tools · Repository upkeep and drift checks · `scripts`
- [Workflows](https://github.com/artificialsenselabs/handbook-public/blob/main/.github/workflows): CI checks · GitHub Actions validation boundary · `.github/workflows`
- [Link check](https://github.com/artificialsenselabs/handbook-public/blob/main/scripts/check-links.py): validation script · Checks internal documentation links · `scripts/check-links.py`
- [External links](https://github.com/artificialsenselabs/handbook-public/blob/main/scripts/check-external-links.py): validation script · Checks outbound links · `scripts/check-external-links.py`
- [Drift check](https://github.com/artificialsenselabs/handbook-public/blob/main/scripts/check-repo-list-drift.sh): validation script · Detects repository list drift · `scripts/check-repo-list-drift.sh`
- [Link CI](https://github.com/artificialsenselabs/handbook-public/blob/main/.github/workflows/link-check.yml): workflow · Runs internal link validation · `.github/workflows/link-check.yml`
- [External CI](https://github.com/artificialsenselabs/handbook-public/blob/main/.github/workflows/external-link-check.yml): workflow · Runs external link validation · `.github/workflows/external-link-check.yml`
- [Drift CI](https://github.com/artificialsenselabs/handbook-public/blob/main/.github/workflows/repo-list-drift.yml): workflow · Runs repo-list drift validation · `.github/workflows/repo-list-drift.yml`

### Governance

Shared standards and operating principles

- [Principles](https://github.com/artificialsenselabs/handbook-public/blob/main/principles/README.md): decision framework · Cross-cutting standards and policy guidance · `principles/README.md`
- [Tooling](https://github.com/artificialsenselabs/handbook-public/blob/main/tooling/README.md): standards · Conventions for commits, semver, pnpm, and actions · `tooling/README.md`
- [Security](https://github.com/artificialsenselabs/handbook-public/blob/main/security/README.md): operating guidance · Workspace security practices and token handling · `security/README.md`

## Connections

- README → Angular: routes to · Top-level navigation into a topic area
- README → Nx: routes to · Top-level navigation into a topic area
- README → CSS/SCSS: routes to · Top-level navigation into a topic area
- README → Debugging: routes to · Top-level navigation into a topic area
- README → How-to: routes to · Top-level navigation into a topic area
- README → Prompts: routes to · Top-level navigation into a topic area
- README → Snippets: routes to · Top-level navigation into a topic area
- README → TIL: routes to · Top-level navigation into a topic area
- README → Principles: routes to · Top-level navigation into cross-cutting guidance
- README → Tooling: routes to · Top-level navigation into standards
- README → Security: routes to · Top-level navigation into security guidance
- README → Contributing: points to · Editorial process and contribution conventions
- Contributing → Templates: uses · New notes follow shared templates
- Contributing → Scripts: relies on · Repository maintenance and link hygiene support the workflow
- Templates → How-to: scaffolds · Template for procedural notes
- Templates → Debugging: scaffolds · Template for troubleshooting notes
- Templates → TIL: scaffolds · Template for short learnings
- Templates → Prompts: scaffolds · Template for reusable prompts
- Principles → Tooling: informs · Shared decision frameworks shape repository conventions
- Principles → Security: informs · Workspace policy and token handling guidance
- Scripts → Link check: contains · Internal link validation tool
- Scripts → External links: contains · Outbound link validation tool
- Scripts → Drift check: contains · Repository drift detection tool
- Link check → Link CI: runs in · CI executes internal link checks
- External links → External CI: runs in · CI executes external link checks
- Drift check → Drift CI: runs in · CI executes repository drift checks
- Link CI → README: protects · Ensures navigation links remain valid
- External CI → README: protects · Ensures outbound references remain valid
- Drift CI → README: protects · Ensures repo-list references stay consistent
- Tooling → Templates: constrains · Conventions influence note structure and naming