Repository Architecture¶
This document describes the purpose of each top-level directory in the Devonshire Digital repository. It is descriptive: it explains what exists and why, not how to write content for each area (see the relevant README.md inside each directory for that).
Root files¶
Root-level files (README.md, AGENTS.md, CLAUDE.md, GEMINI.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, NOTICE.md, CHANGELOG.md) are the entry points a human or AI agent encounters first when opening this repository. They orient the reader, set operating rules for AI agents working in the repo, and carry the provisional proprietary notice (see docs/decisions/ADR-0008-private-and-proprietary-default.md).
docs/¶
The primary documentation tree, organized by audience and purpose rather than by venture:
docs/company/— company identity, mission, principles, and commercialization philosophy. Applies to Devonshire Digital as a whole.docs/governance/— the rules that govern how this repository itself is run: authority, change management, information classification, and similar structural policy.docs/ai/— operating instructions for AI agents working in this repository, distinct from human-facing company documentation (seedocs/decisions/ADR-0004-separate-human-and-ai-documentation.md).docs/architecture/(this directory) — the structural shape of the repository and the company/venture/product model.docs/standards/— company-wide, checkable rules (naming, writing, QA, security, accessibility, and so on) that apply across ventures.docs/decisions/— Architecture Decision Records (ADRs) capturing material, hard-to-reverse decisions.
portfolio/¶
Machine-readable registries (JSON) that index ventures, products, and related repositories with stable IDs. See registry-architecture.md for detail. The registries are metadata and indexes; the authoritative narrative content remains in Markdown.
ventures/¶
One directory per venture, plus a _template/ directory that defines the expected internal structure for a new venture. Each venture directory (e.g., ventures/shelfery/, ventures/digital-products/) holds venture-specific context, standards, decisions, and AI instructions that extend — but do not contradict — company-level documentation. See company-venture-product-model.md.
templates/¶
Reusable starting structures for recurring document types: the ADR template, product specification templates, component specification templates, and similar. Venture-specific templates may live inside a venture's own directory instead, when they extend a company-level template with venture-specific sections.
prompts/¶
Reusable prompt text intended for use with AI tools, kept separate from operating instructions (docs/ai/) because prompts are inputs to a task rather than standing rules for agent behavior.
work/¶
Working documents with a shorter shelf life than formal specifications or standards: active plans, in-progress notes, and similar material. Superseded or completed material is retained under work/archive/ rather than deleted; see docs/standards/archival-and-retention-standard.md.
schemas/¶
JSON Schema definitions (e.g., schemas/venture.schema.json) used to validate the registries in portfolio/ and other structured data in the repository.
scripts/¶
Tooling that operates on the repository itself — validation, checks, and automation, preferring Python's standard library where practical (see docs/standards/dependency-and-tooling-standard.md).
tests/¶
Automated tests for the tooling in scripts/ and for structural validation of the repository's documentation and registries.
.claude/ and .github/¶
Tool-specific configuration: .claude/ configures the Claude Code environment for this repository; .github/ holds GitHub-specific configuration (issue templates, workflows, and similar), used for repository mechanics even though this repository has no public remote at present.
Cross-cutting note¶
This layout supports the company operating as a documentation and governance source of truth first, with product implementation code placed here, in separate repositories, or in a hybrid arrangement — that boundary is an open decision. See future-repository-strategy.md and docs/decisions/ADR-0007-implementation-repository-boundary-remains-open.md.