Skip to content

docs: split architecture into docs/architecture/ detail docs and overview index #63

@mikanmarusan

Description

@mikanmarusan

Goal

Make the x-syncing-specs skill engage and establish the spec-docs IA. Today there is no docs/architecture/ directory, so the skill exits no-drift ("not a spec-sync target"). This issue migrates the detail sections out of the single docs/architecture.md into per-subsystem detail docs (redacting leaked identifiers along the way) and reduces docs/architecture.md to a thin overview/index. (The CLAUDE.md spec-doc: marker is wired in a separate issue.)

Your Task

  1. Create docs/architecture/ and move (do not copy) the detail sections out of docs/architecture.md:
    New detail doc Section(s) moved
    docs/architecture/jorudan-cookie-flow.md "Jorudan Bot Detection — 3-Step Cookie Flow" + safeJoinUrl() SSRF guard
    docs/architecture/html-parsing.md "HTML Parsing" + escapeRegExp() ReDoS guard
    docs/architecture/api-contract.md "API Path Normalization" + "Response Format"
    docs/architecture/observability.md "Observability"
    docs/architecture/deploy-and-iam.md "Production Deploy Constraint" + "CI/CD Deploy Role IAM Policy" (policy JSON)
  2. Each detail doc opens with # Heading + a breadcrumb line > Part of [Architecture overview](../architecture.md). (breadcrumb stays outside any managed region).
  3. Managed-region markers only on code-derived docs: jorudan-cookie-flow.md, html-parsing.md, api-contract.md each wrap their migrated body in <!-- spec-synced-through: a710d8f --><!-- /spec-synced-through -->. observability.md and deploy-and-iam.md carry NO marker (ops/runbook/rationale with no code source to reconcile — leaving them marker-free keeps x-syncing-specs from overwriting hand-written ops info).
  4. Redact every real identifier during migration (especially in deploy-and-iam.md): 470021024556<ACCT>, and resource IDs → <CF_DISTRIBUTION_ID> / <OAC_ID> / <REST_API_ID> / <SAM_ARTIFACT_BUCKET> / <FRONTEND_BUCKET>, matching the existing <ACCT> convention in CLAUDE.md.
  5. Fix relative-link depth in moved content (one level deeper): ../CLAUDE.md../../CLAUDE.md, ../template.yml../../template.yml, ../.github/...../../.github/....
  6. Reduce docs/architecture.md to an overview/index: keep title, intro, the High-Level Architecture table, and the diagram links (./diagrams/... paths unchanged); replace the removed detail sections with a "Detail Documents" table linking the five new docs. Leave overview prose outside any managed-region marker.

Context

  • Source plan: .plans/planning-adr-spec-docs-20260620.md (Tasks 4–5; Codex finding Add Claude Code GitHub Workflow #1 on marker scoping; Security T1 on identifier redaction).
  • a710d8f is the current HEAD SHA at plan time; it anchors the next on-demand sync's diff range.
  • x-syncing-specs writes only docs/architecture.md + docs/architecture/** — no overlap with docs/adr/**.

Warning

  • This change MUST remove the real account ID 470021024556 from the working tree (it appears 12× in docs/architecture.md today). After migration the identifier grep must be clean — the skills' sensitive-scan does not run on this manual edit and would not match a bare account ID anyway.
  • Move content, never duplicate it: a fact must live in exactly one of the overview vs a detail doc, or the docs drift.
  • CI has no link checker, so verify every relative link by hand.

Acceptance Criteria

  • test -d docs/architecture && ls docs/architecture/jorudan-cookie-flow.md docs/architecture/html-parsing.md docs/architecture/api-contract.md docs/architecture/observability.md docs/architecture/deploy-and-iam.md all exist.
  • grep -rEn '470021024556|E58KEXJEHRAN5|EE7PDHZSW7GW8|63zlpdau7f|samclisourcebucket-[a-z0-9]+|arn:aws:[a-z0-9-]+:[a-z0-9-]*:[0-9]{12}:' docs/architecture docs/architecture.md returns no matches.
  • grep -l 'spec-synced-through' docs/architecture/*.md lists exactly the three code-derived docs (jorudan-cookie-flow, html-parsing, api-contract) and NOT observability.md or deploy-and-iam.md.
  • Each of the three code-derived docs contains exactly one opening <!-- spec-synced-through: a710d8f --> marker.
  • Every relative link in docs/architecture.md and docs/architecture/*.md resolves: for each ](./...) / ](../...) target, test -e from the file's own directory exits 0.
  • docs/architecture.md no longer contains the migrated detail bodies (e.g. grep -c 'set-uuid.cgi' docs/architecture.md returns 0) and has a "Detail Documents" table linking the five docs.

Metadata

Metadata

Assignees

No one assigned

    Labels

    loop:readyReady for the autonomous fix loop

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions