Kickoff

Task

Produce the Item Image Upload system design documents.

Goal File

Read index.md in this directory first — it is the authoritative specification for this task. It defines the goal, actors, design decisions (TD-01 through TD-07), deliverable structure, scenario inventory (S1–S7), and conventions.

What to Produce

9 new Markdown files in this directory (system-design/) alongside index.md. The index.md already exists and must not be modified.

System-Level Documents

File	Content
requirements.md	FR-NNN / NFR-NNN requirements with traceability to use cases. Also includes User actor behavioral assumptions.
scenarios.md	PlantUML sequence diagrams for S1–S7 with narratives.
oam-requirements.md	FCAPS model OAM requirements.
risks-and-assumptions.md	Risks, obstacles, assumptions, migration concerns.
phasing.md	Phasing recommendation based on dependency structure.

Per-Actor Documents

Each has 4 sections: Requirements, Interfaces, State, Modules.

File	Actor
actor-spa.md	SPA (React)
actor-bff.md	BFF (Next.js)
actor-backend.md	Backend (Operations / common-module)
actor-aws.md	AWS Resources

How to Work

1. Read All References First

The index.md References section lists every source document. Read them all before writing anything. Key files:

• documentation/src/content/docs/product/features/general-behaviors/entity-behaviors/entity-media.md
• documentation/src/content/docs/product/features/reference-data/items/items.md
• documentation/src/content/docs/product/use-cases/general-behaviors/entity-behaviors/entity-media.md
• documentation/src/content/docs/product/use-cases/reference-data/items/items.md
• documentation/src/content/docs/roadmap/completed/item-image-upload/use-case-definition/index.md
• documentation/src/content/docs/roadmap/completed/item-image-upload/scoping.md
• documentation/src/content/docs/roadmap/completed/item-image-upload/decision-log.md
• documentation/src/content/docs/roadmap/completed/item-image-upload/previous-design-work/static-assets.md
• documentation/src/content/docs/roadmap/completed/item-image-upload/previous-design-work/12-upload-product-images/project-description.md
• documentation/src/content/docs/roadmap/completed/item-image-upload/ux-design/components/components.md
• documentation/src/content/docs/current-system/ (explore for architecture context)

2. Load Skills Before Writing

Invoke these skills and follow their conventions:

• design-document — document template and structure
• plantuml-diagrams — diagram syntax, validation, conventions
• document-writing — frontmatter, links, formatting

3. Write Documents in Dependency Order

1. requirements.md first (other docs reference it)
2. scenarios.md (actor docs reference scenarios)
3. The 4 actor documents (actor-spa.md, actor-bff.md, actor-backend.md, actor-aws.md)
4. oam-requirements.md
5. risks-and-assumptions.md
6. phasing.md last (it synthesizes the whole design)

4. Validate Every PlantUML Diagram

Use the PlantUML MCP tool (generate_plantuml_diagram) before writing a diagram to a file. Render to SVG in scratch/ to confirm. Do not commit unvalidated diagrams.

5. Traceability Is Mandatory

• Every requirement must link to the use case(s) it derives from.
• Every scenario must reference the use case IDs and TD-NN decisions it implements.
• Every actor requirement/interface must reference the scenario(s) it supports.

6. Respect Design Decisions TD-01 Through TD-07

These are binding. Key points:

• TD-01: All images end up in managed storage — external URLs are fetched SPA-side, edited, then uploaded.
• TD-02: SPA attempts URL reachability directly; BFF is a CORS fallback only, never checks our own storage.
• TD-03: Presigned credentials generated by Backend (Operations), proxied through BFF.
• TD-04: Copyright acknowledgment is SPA-only, no backend logging.
• TD-05: With fetch-and-store, all persisted image URLs originate from managed storage. Backend validates URLs match expected CDN host and key pattern. External URLs are never persisted directly.
• TD-06: File bytes go directly SPA → Storage; BFF/Backend only broker credentials and metadata.
• TD-07: Sequence diagrams use “Storage” as a single black-box participant; AWS specifics only in actor-aws.md.

7. Prior Design Work Is Informative, Not Binding

Use it for background context but make independent design choices. If you diverge from prior work, note it briefly.

8. Append New Decisions to Existing Decision Log

If new design questions arise during writing, append them to the existing decision-log.md (in the parent directory) under a new ## System Design (YYYY-MM-DD) section. Use TD-NN numbering continuing from TD-07.

9. Document Conventions

• Use .md extension on all internal links.
• Use **** for horizontal rules.
• Frontmatter: domain: roadmap, maturity: draft, author: "Arda Systems".
• Footer: Copyright: (c) Arda Systems 2025-2026, All rights reserved.

Recommended Skills and Agent Profiles

Skills to Load

These skills must be loaded (via the Skill tool) before writing. They define the formatting rules, diagram conventions, and document structure that all deliverables must follow.

Skill	Purpose	When
design-document	Design document template — section structure, decision traceability, scope management.	Before writing any deliverable.
plantuml-diagrams	PlantUML syntax, validation workflow, sequence/class diagram conventions, common pitfalls.	Before writing scenarios.md or any diagram.
document-writing	Frontmatter, Markdown formatting, link conventions, admonitions, Starlight authoring rules.	Before writing any deliverable.
path-conventions	Cross-repo path references and Markdown link rules.	When writing links between documents.
decision-log	Decision log format — open-questions table, round protocol, resolution workflow.	When appending decisions to decision-log.md.

Skills to Consult for Domain Knowledge

These skills carry domain and technical knowledge relevant to specific deliverables. Load them selectively.

Skill	Purpose	Relevant Deliverables
kotlin-coding	Kotlin backend conventions — Result handling, AppError hierarchy, Exposed ORM, null semantics.	actor-backend.md (interfaces, modules)
unit-tests-infra	ContainerizedPostgres, LocalStack/MockAWS, Harness pattern for test infrastructure.	actor-backend.md, actor-aws.md (testing strategy)
knowledge-base	Index of accumulated project knowledge — check for relevant entries on operations, frontend, infrastructure.	All deliverables (background context)
general-conventions	Workspace-wide conventions — stdout redirect, IntelliJ formatting, agent branch naming.	All deliverables (process alignment)

Agent Profiles for Subagent Delegation

If this task is executed by a team lead or coordinator, these agent profiles are recommended for delegation. Each profile carries specialized expertise and produces artifacts in its domain.

Agent Profile	Recommended For	Deliverables
principal-engineer	Architecture decisions, cross-module impact analysis, interface design. AWS/Kotlin/TypeScript/REST expertise.	scenarios.md, actor-backend.md, actor-aws.md, phasing.md
technical-writer	Document production, PlantUML diagrams, information architecture. Never writes production code.	All documents — primary authoring agent.
domain-architect	Entity modeling, domain concepts, data model alignment (three-layer model: Reference, Resources, Procurement).	requirements.md, actor-backend.md (state, interfaces)
security-engineer	Threat modeling, tenant isolation, presigned URL security, OWASP concerns.	oam-requirements.md (Security Management), risks-and-assumptions.md
devops-engineer	AWS CDK, S3/CloudFront configuration, IAM policies, CI/CD implications.	actor-aws.md, oam-requirements.md (Fault/Config/Performance Management)
domain-expert	Logistics/manufacturing domain reasoning, first-principles process analysis.	requirements.md (domain-grounded requirements)
product-owner	Use case traceability, acceptance criteria, scoping validation.	requirements.md (traceability review)

Observation Logging (Mandatory)

This is the first system-level design produced by the Arda workspace. An observation log has been seeded with pre-execution observations from the kickoff session. The implementing agent must append observations during execution to support future skill development.

Log file: implementation/observations.md (in this directory)

What to log — append an entry whenever you:

• Get stuck or have to backtrack (FRICTION)
• Discover a pattern that could be templated (CONTENT)
• Wish a skill or convention existed (MISSING)
• Find that an existing skill was helpful or insufficient (INSIGHT)
• Make a process choice that worked well or poorly (PROCESS)

Format: Use ### OBS-NNN — CATEGORY: Title with a date and description. Continue numbering from OBS-010 (pre-execution entries are OBS-001 through OBS-010).

Frequency: At minimum, log one observation per deliverable completed. More frequent logging is welcome — capturing friction in the moment is more valuable than reconstructing it later.

After completion: The observation log will be consumed by an improvement-analyzer agent to propose new skills, templates, and conventions for future system-level design work.

Suggested Execution Strategy

For a single-agent execution, use the principal-engineer profile with technical-writer as the authoring voice — the principal engineer has the broadest technical knowledge to make sound interface and architecture choices.

For a team execution, a recommended split:

1. Phase 1 (sequential — establishes the foundation):

   • technical-writer writes requirements.md (with domain-expert or product-owner review)
   • principal-engineer writes scenarios.md (with PlantUML validation)

2. Phase 2 (parallel — actor docs are independent):

   • principal-engineer writes actor-backend.md and actor-aws.md
   • technical-writer writes actor-spa.md and actor-bff.md

3. Phase 3 (sequential — synthesizes prior work):

   • security-engineer + devops-engineer write oam-requirements.md
   • principal-engineer writes risks-and-assumptions.md
   • principal-engineer writes phasing.md (must read all prior deliverables)

---

Copyright: (c) Arda Systems 2025-2026, All rights reserved