artificialsenselabs/handbook-public

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.