Skip to content

Documentation Tree Structure

⚠ Historical / planning document.

This file was authored when the audit assumed the documentation would live in a doc/ directory inside the someli-api repo (and similar doc/ subdirectories inside other repos). That target was not adopted. The realized organization is someli-doc/ — a separate directory parallel to the cloned source repos, not committed to any of them. The actual structure is documented at someli-doc/README.md.

Below is the original target structure, kept for historical reference. Where it says doc/ or doc/<component>/, the realized equivalent is someli-doc/audit/<component>/.

This document describes the originally proposed target organization of the Someli platform documentation tree. It is a planning / reference document — the actual file moves to reach this structure can be done as a one-time reorganization once the web client and admin dashboard audits complete.

Why this exists: the TDD Report treats the documentation tree as the canonical source of truth (master documents are derived from doc-tree information, not from code). For that to work, the tree organization must be deliberate and documented.

Target structure

doc/                                          # Documentation root
│
├── README.md                                 # Top-level index pointing at master + components
│
├── (master / full-picture documents)         # Platform-level docs
│   ├── tdd-report.md                         # THE TDD master report (consumed by board, customers, acquirers)
│   ├── platform-architecture.md              # Cross-component architecture overview
│   ├── platform-security.md                  # Cross-component security posture
│   ├── platform-roadmap.md                   # Unified roadmap (component-tagged)
│   ├── platform-risk-register.md             # Unified risk register
│   ├── platform-maturity.md                  # Platform maturity assessment
│   ├── compliance-cross-walk.md              # SOC 2 / ISO 25010 / OWASP SAMM / AWS WAF
│   ├── glossary.md                           # Cross-component terminology
│   ├── doc-tree-structure.md                 # ← this document
│   └── verify-markers.md                     # Platform-level [VERIFY] tracker
│
├── api/                                      # someli-api component subtree
│   ├── README.md                             # Component-level index
│   ├── architecture-overview.md
│   ├── data-model.md
│   ├── API-inventory.md
│   ├── authentication.md
│   ├── content-pipeline.md
│   ├── agents-and-ai.md
│   ├── user-specific-ai.md
│   ├── rag-pipeline.md
│   ├── media-processing.md
│   ├── notifications.md
│   ├── jobs-inventory.md
│   ├── dashboard-analytics.md                # Note: this is the EMBEDDED analytics sub-app, not the standalone admin dashboard
│   ├── deployment.md
│   ├── configuration.md
│   ├── Integration-inventory.md
│   ├── dependencies-inventory.md
│   ├── error-handling.md
│   ├── logging-observability.md
│   ├── security.md
│   ├── realtime-events.md
│   ├── getting-started.md
│   ├── first-deployment.md
│   ├── verification-report.md                # Quantitative-claim audit
│   ├── verification-report-control-flow.md   # Narrative-claim audit
│   ├── visuals-tracking.md
│   ├── enterprise-readiness.md               # Strategic / readiness deliverable for this component
│   ├── maturity-model.md                     # Methodology used in enterprise-readiness.md
│   ├── engineering-charter.md
│   ├── engineering-practices.md
│   ├── definition-of-done.md
│   ├── pr-template-reference.md
│   └── someli-schema.sql                     # The source-of-truth schema dump
│
├── web-client/                               # Web client component subtree (TBD)
│   ├── README.md                             # Component-level index
│   ├── architecture-overview.md              # Frontend architecture
│   ├── routing-and-state.md                  # SPA routing, state management
│   ├── api-consumption.md                    # How the client talks to the API
│   ├── authentication-client.md              # Token storage, refresh, session handling
│   ├── ui-component-library.md               # Design system / component inventory
│   ├── accessibility.md                      # WCAG posture
│   ├── performance.md                        # Bundle, Core Web Vitals
│   ├── security.md                           # CSP, XSS, dependency CVEs
│   ├── testing.md                            # Unit / integration / e2e
│   ├── build-and-deploy.md
│   ├── observability.md                      # Sentry, RUM, analytics
│   ├── i18n.md                               # Internationalization
│   ├── seo-and-metadata.md
│   ├── dependencies-inventory.md
│   ├── verification-report.md
│   └── enterprise-readiness.md
│
└── admin-dashboard/                          # Admin dashboard component subtree (TBD)
    ├── README.md
    ├── architecture-overview.md
    ├── access-control.md                     # RBAC, role definitions, route guards
    ├── audit-logging.md                      # Admin-action audit trail
    ├── api-consumption.md                    # Admin-only API endpoints exercised
    ├── authentication-client.md              # Often distinct from web client (e.g., MFA-required)
    ├── sensitive-data-handling.md            # PII display, masking, redaction
    ├── ui-component-library.md
    ├── performance.md
    ├── security.md
    ├── testing.md
    ├── build-and-deploy.md
    ├── observability.md
    ├── dependencies-inventory.md
    ├── verification-report.md
    └── enterprise-readiness.md

Naming conventions

Convention Rationale
kebab-case.md for filenames Web-friendly URLs; avoids case-sensitivity issues across OS
architecture-overview.md always exists at the top of each component First doc a new contributor reads
dependencies-inventory.md always exists at the top of each component Source of truth for hygiene
verification-report.md always exists at the top of each component Audit trail per component
enterprise-readiness.md always exists at the top of each component Strategic / readiness deliverable per component
README.md always exists at the top of each component Component-level index
Integration-inventory.md (capital I) — exception to the kebab-case rule, kept for compatibility with existing links Pragmatic

Why this organization

Component subtrees mirror real-world ownership

Each component subtree is fully self-contained. The web client's docs sit next to its own dependencies inventory, its own readiness deliverable, its own audit trail. A team taking ownership of one component reads its subtree and has everything they need.

Master documents enable platform-level views

Without the master layer, anyone wanting "the platform's security posture" would have to read three components' security docs and synthesize. The master layer does that synthesis once, in writing, and is updated whenever a component changes.

The TDD report is the consumable executive artifact

tdd-report.md is the document a board member, an enterprise customer's procurement reviewer, or an acquirer's technical due-diligence team would read. It pulls from the masters and the appendices but stands alone as a complete narrative.

"Generated from docs, not from code"

The constraint stated when this organization was designed: master docs are generated from the documentation tree, not from re-reading the codebase. This means:

  • Component documentation must be comprehensive — sufficient that the master doc author doesn't need to re-read code
  • Component documentation must be accurate — enforced by the verification-report.md per-component audit cycle
  • Component documentation must be current — refreshed when the component changes

The engineering-practices.md rules ("if endpoint added → OpenAPI spec updated in this PR; if schema changed → migration file added; if new env var → added to configuration.md") exist to keep component docs current.

How a master document is produced

  1. Read the per-component docs for the cross-cutting topic (e.g., security)
  2. Synthesize the platform-level picture from the components' findings
  3. Cite each component doc as the source for component-specific claims
  4. Identify drift between components (e.g., backend uses one auth pattern, web client uses another)
  5. Produce the master document as a synthesis, not a copy

When a component's findings change, the master is refreshed by re-running this process — not by ad-hoc edits.

How a component is added

When a new component (e.g., a mobile app, a partner-portal microservice) is added:

  1. Create the subtree directory: doc/<component-name>/
  2. Populate the standard files (README.md, architecture-overview.md, dependencies-inventory.md, verification-report.md, enterprise-readiness.md minimum)
  3. Run the same audit methodology used for api/ (codebase inspection, schema verification, control-flow verification)
  4. Update the master TDD report's §3 (Architecture), §5 (Per-component findings), §6 (Risk Register), §7 (Roadmap)
  5. Bump the TDD report version (v0.1 → v0.2 → v0.3 → v1.0)

Migration to this structure

The existing documentation is currently flat under doc/. Migration to the target structure requires:

  1. Create subtree directories: doc/api/, doc/web-client/, doc/admin-dashboard/
  2. Move existing files into doc/api/ — most of the current doc/*.md files belong here
  3. Identify master documents and leave them at doc/ root (or in a doc/platform/ subdirectory if preferred):
  4. tdd-report.md
  5. doc-tree-structure.md (this file)
  6. verify-markers.md (or split: per-component markers in subtrees, platform markers at root)
  7. The README index
  8. Update relative paths in all internal links — most existing links assume flat structure
  9. Author new component subtrees for web client and admin dashboard during their respective audits

Recommendation: defer the file moves until the web client and admin dashboard audits are at least underway. Premature reorganization leaves dangling links across docs that haven't been touched recently. Once components 2 and 3 are being authored, do the migration as a single large PR.

A perennial maintenance concern with multi-tree documentation:

  • Internal links use relative paths so the tree can be moved without rewriting links
  • Master → component links use <component>/<file>.md
  • Component → component links are discouraged (cross-component references should go through the master layer)
  • Component → master links are common (e.g., ../tdd-report.md)

A periodic find . -name '*.md' -exec markdown-link-check {} \; (or equivalent) sweep catches dangling links.

Versioning

Each master document has a version field at the top (Version: 0.1, 0.2, etc.). Each component subtree's README.md has a "last verified" date.

When a component is re-audited: - Bump the component's verification-report.md date - Update any specific docs whose findings changed - Refresh the relevant master documents

What lives where — quick reference

Question Where to look
"What's the platform's security posture?" tdd-report.md §4.1, platform-security.md (when authored)
"What does the API auth flow look like?" api/authentication.md
"Which dependencies does the web client use?" web-client/dependencies-inventory.md (when authored)
"What's the maturity rating?" tdd-report.md §5.4 (platform), <component>/enterprise-readiness.md (per-component)
"What's on the roadmap?" tdd-report.md §7 (consolidated), or each component's enterprise-readiness.md §6
"What's the audit trail?" <component>/verification-report.md
"How is the documentation organized?" doc-tree-structure.md (this file)
  • TDD Report — the master executive report this tree supports
  • README — top-level documentation index