Create docs/architecture/ README + SVG placeholder stubs #58

New issue

Closed

opened 2026-05-25 15:04:12 -03:00 by navigator · 2 comments

navigator commented

2026-05-25 15:04:12 -03:00

Owner

Goal

Create the docs/architecture/ directory with placeholder stubs for the two block diagrams listed as deliverables #6 and #7 in PLAN.md Section 10 (chip-block.svg and board-block.svg). Since these are SVG deliverables that require actual block-diagram design work, this issue creates plain-text TODO placeholder files plus a README that describes the intended content of each diagram so future design work has clear targets.

Files to create:

docs/architecture/README.md — describes the directory, lists each diagram, links back to relevant PLAN.md sections
docs/architecture/chip-block.svg.TODO — text file describing required content for chip-level block diagram (4 Gemminis, 4x4 xbar, 2 Rocket cores, 256 KiB scratchpad, DDR5 controller, PopLink fabric ports, optional PCIe host bridge for master variant)
docs/architecture/board-block.svg.TODO — text file describing required content for board-level block diagram (8 SoCs in 2x4 torus, designated master, 8 DDR5 DIMMs, cold plate envelope, BMC, PCIe Gen4 x16 host link, OAM 2.0 form factor)

Acceptance criteria

docs/architecture/README.md exists and lists both diagrams with intended scope
docs/architecture/chip-block.svg.TODO enumerates required blocks per Section 8.1 chip-level ADRs (ADR-001 through ADR-007) and PHY interface per Section 13.3
docs/architecture/board-block.svg.TODO enumerates required blocks per Section 8.1 board-level ADRs (ADR-008 through ADR-014)
No actual SVG content created — only TODO text placeholders (real SVG design is separate downstream work)
README explicitly notes that the SVGs replace these .TODO files when ready

Plan refs

Section 10 (deliverables #6 and #7); Section 8.1 (chip-level and board-level ADRs informing diagram content); Section 13.3 (PHY interface to include in chip diagram)

Notes

The .TODO suffix avoids creating empty/invalid SVG files in the repo. When a contributor produces a real diagram, they replace the .TODO with the .svg. Pure scaffolding — no design decisions are made here.

## Goal Create the `docs/architecture/` directory with placeholder stubs for the two block diagrams listed as deliverables #6 and #7 in PLAN.md Section 10 (`chip-block.svg` and `board-block.svg`). Since these are SVG deliverables that require actual block-diagram design work, this issue creates plain-text TODO placeholder files plus a README that describes the intended content of each diagram so future design work has clear targets. Files to create: - `docs/architecture/README.md` — describes the directory, lists each diagram, links back to relevant PLAN.md sections - `docs/architecture/chip-block.svg.TODO` — text file describing required content for chip-level block diagram (4 Gemminis, 4x4 xbar, 2 Rocket cores, 256 KiB scratchpad, DDR5 controller, PopLink fabric ports, optional PCIe host bridge for master variant) - `docs/architecture/board-block.svg.TODO` — text file describing required content for board-level block diagram (8 SoCs in 2x4 torus, designated master, 8 DDR5 DIMMs, cold plate envelope, BMC, PCIe Gen4 x16 host link, OAM 2.0 form factor) ## Acceptance criteria - [ ] `docs/architecture/README.md` exists and lists both diagrams with intended scope - [ ] `docs/architecture/chip-block.svg.TODO` enumerates required blocks per Section 8.1 chip-level ADRs (ADR-001 through ADR-007) and PHY interface per Section 13.3 - [ ] `docs/architecture/board-block.svg.TODO` enumerates required blocks per Section 8.1 board-level ADRs (ADR-008 through ADR-014) - [ ] No actual SVG content created — only TODO text placeholders (real SVG design is separate downstream work) - [ ] README explicitly notes that the SVGs replace these .TODO files when ready ## Plan refs Section 10 (deliverables #6 and #7); Section 8.1 (chip-level and board-level ADRs informing diagram content); Section 13.3 (PHY interface to include in chip diagram) ## Notes The .TODO suffix avoids creating empty/invalid SVG files in the repo. When a contributor produces a real diagram, they replace the .TODO with the .svg. Pure scaffolding — no design decisions are made here.