Overview

Goal

Create a top-level system design specifying interfaces, dependencies, and interactions between the layers of the system and what Apps, Components, and Resources support the Item Image Upload use cases.

References

Requirements and Scoping

• General Image Upload Features — GEN::MEDIA feature specification (FR-0001 through FR-0020)
• Item Management Features — REF::ITM feature specification (FR-0001 through FR-0008)
• General Image Upload Use Cases — GEN::MEDIA::0001 (Set), 0002 (Remove), 0003 (View)
• Item Image Upload Use Cases — REF::ITM::0003::0010 (Create), 0004::0006 (Edit)
• Use Cases Analysis — Key decisions and rationale
• Scoping — In/out-of-scope determination per scenario
• Project Decision Log — All project decisions (SD-01 through SD-16, CD-01 through CD-09, UD-01 through UD-03)

Prior Design Work (Informative Only)

The following documents are informative background. They are not binding on this system design — decisions made here may diverge from prior work.

• Previous Design Work — Earlier infrastructure and interaction design
• Static Asset Repository — FileStore concept (presigned URLs, S3, CDN)
• Upload Product Images Project — Earlier project description with design questions
• Current System — Existing system architecture documentation

UX Design

• UX Component Specification — 19 components across 6 tiers
• UX Use Case Stories — Storybook story specifications

Actors

#	Actor	Description	Repository
1	User	Human accessing the system through a modern web browser	—
2	SPA	Browser single-page application (React)	arda-frontend-app
3	BFF	Next.js server application (Backend-for-Frontend pattern)	arda-frontend-app
4	Backend	Business services (REST APIs). Main component: operations. Shared library: common-module.	operations, common-module
5	AWS Resources	S3, CloudFront, and other cloud resources. Treated as a black box in scenario definitions; specific resources identified in the actor document.	infrastructure

The referenced repositories do not contain any capabilities related to this feature yet.

Actor Dependency Diagram

Arrows point from the actor that initiates interactions or has advance knowledge of the other’s interface.

Note

The BFF does not depend on AWS Resources. Reachability checks and image fetching by the BFF target external URLs only — as a fallback when the SPA cannot fetch them directly due to CORS. Assets in our own storage are accessed directly by the SPA (CDN read) or verified by the Backend.

Design Decisions

Decisions made during the system design session. Recorded in the Project Decision Log under the “System Design” section.

Id	Topic	Decision
TD-01	Fetch-and-store for external URLs	SPA-side. When a user provides an external HTTPS URL, the SPA fetches the image, renders it in the editor for crop/zoom/rotate, then uploads via the managed presigned-upload path. No server-side fetch.
TD-02	URL reachability check	SPA with BFF fallback. The SPA attempts the reachability and content-type validation directly. If CORS blocks the request, the BFF proxies the HEAD (or full GET) against the external URL. The BFF never checks URLs on our own storage — those are known-good.
TD-03	Presigned credential generation	Backend (Operations). Operations generates presigned POST credentials. The BFF proxies the request, adding auth headers and tenant context.
TD-04	Copyright acknowledgment	SPA-only. The upload itself is evidence of acceptance. No backend logging of the acknowledgment. Further recording is a follow-up improvement if needed.
TD-05	Backend URL validation	Tightened. With fetch-and-store, all persisted image URLs originate from managed storage. The backend validates that provided URLs match the expected CDN host and key pattern. External URLs are never persisted directly.
TD-06	Direct payload transfer	Client-to-storage. Pure file payload uploads go directly from the SPA to S3 using presigned credentials. The BFF and backend are not in the data path for file bytes — they only broker credentials and persist metadata.
TD-07	AWS resources abstraction	Black box in scenarios. Sequence diagrams reference “Storage” as a single participant. Specific AWS resources (S3 buckets, CloudFront distributions, IAM roles) are identified in module identification only.

Deliverables

Documents are organized into system-level pages and per-actor pages. Each actor page consolidates the actor’s requirements, interfaces, state, and modules into a single document.

System-Level Documents

File	Content
index.md	This page — goal, references, sub-systems, dependency diagram, decisions, scenario inventory, conventions.
design.md	Structural design — sub-system responsibilities, information ownership, dependency diagram, write/read path data flows, shared interface contracts (object key convention, presigned POST, CDN access control). Read first for technical context.
requirements.md	FR-NNN (functional) and NFR-NNN (non-functional) requirements derived from references. Each requirement must be verifiable by an independent agent once the system is built. Includes traceability links to source use cases. Also contains User behavioral assumptions.
scenarios.md	Sequence diagrams (PlantUML) with narrative for each in-scope use case. Happy path focus; error paths in narrative. Traceability to use case IDs and design decisions.
oam-requirements.md	Operations, Administration, and Maintenance requirements following the FCAPS model: Fault, Configuration, Performance, Security, and Accounting Management.
risks-and-assumptions.md	Risks, obstacles, and assumptions the design makes, including pre-existing data migration concerns. Items may be out of scope for implementation but must be recorded for project-level tracking.
phasing.md	Recommended implementation phasing based on capability dependencies identified in the design. Final phasing decision is a separate deliverable outside this session.

Per-Sub-System Documents

Each sub-system document contains four sections: Requirements (functional and non-functional), Interfaces (API contracts and component interfaces), State (information the sub-system maintains), and Modules (modules to develop or modify). All sections include traceability links to scenarios, requirements, and decisions. See design.md for the structural overview.

File	Sub-System	Notes
spa-specification.md	SPA (React)	Input detection, editor, upload orchestration, CDN rendering.
bff-specification.md	BFF (Next.js)	API proxy, URL reachability check, cookie signing, auth enrichment.
backend-specification.md	Backend (Operations / common-module)	Presigned credential generation, entity persistence, URL validation.
aws-specification.md	Storage (AWS Resources)	Specific resource identification (S3 buckets, CloudFront, IAM). Black box in scenarios; detailed here.

Scenario Inventory

Based on the Scoping document, the following scenarios require sequence diagrams. Scenarios that share the same system interactions at the actor level (e.g., different SPA viewing modes that require no BFF/backend differentiation) are consolidated into a single scenario.

Scenario	Use Cases Covered	Notes
S1: Upload Image (Managed Path)	GEN::MEDIA::0001::0001.UC, 0002.FS (file/drag-drop/clipboard), 0003.FS (formats/limits), 0005.FS (preview/crop), 0006.FS (confirm/persist)	Primary scenario. Covers: SPA validates → BFF proxies upload-url request → Backend generates presigned credentials → SPA uploads to Storage → SPA persists entity via BFF/Backend.
S2: Set Image from External URL	GEN::MEDIA::0001::0002.FS (URL text entry), 0004.FS (URL validation)	Fetch-and-store variant. SPA sends URL to BFF for reachability check → BFF validates → SPA fetches image → SPA renders in editor → then follows S1 upload path.
S3: Remove Image	GEN::MEDIA::0002::0001.UC	SPA confirms with user → updates entity via BFF/Backend with null image reference.
S4: View Image (Read Path)	GEN::MEDIA::0003::0001.UC (grid thumbnail), 0002.FS (hover quick inspection), 0003.FS (fallback/error)	Single scenario: SPA retrieves entity with image URL → renders from CDN via signed cookies. Hover popover for quick inspection. Error/fallback handling is SPA-internal.
S5: Grid Inline Edit	GEN::MEDIA::0001::0007.FS	Own scenario. Entry point differs (grid cell edit trigger). References S1 for upload mechanics. Highlights that system uses existing entity data as the “current image” source.
S6: Set Image During Item Creation	REF::ITM::0003::0010.UC	Item-specific. Image upload interleaved with item creation. References S1 for upload mechanics.
S7: Change/Remove Image During Item Edit	REF::ITM::0004::0006.UC	Item-specific. Combines S1 (change) or S3 (remove) within the item edit flow.

Conventions

• Diagrams: PlantUML per PlantUML Guide. Validate all diagrams before committing.
• Document format: Per Design Document template and Authoring Guide.
• Decision traceability: New decisions recorded in the Project Decision Log under a “System Design” section with TD-NN identifiers. All deliverables include traceability links back to the source use cases, requirements, and decisions that inform them.
• DRY principle: Scenarios that share system-level interactions reference the primary scenario rather than repeating details. Actor documents reference scenarios by ID rather than duplicating sequence descriptions.
• Links: Use .md extension on all internal links per documentation site conventions.

---

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