System Design Results
This directory contains the system design deliverables for the Item Image Upload feature. These documents were produced from the goal specification in index.md and the task definition in kickoff.md.
How to Read
Section titled “How to Read”Start with the overview document, then read the system-level documents in order — each builds on the previous. The design document provides the structural context that all other documents build on. Then read the sub-system specifications in any order (they are independent of each other). Finish with the synthesis documents.
Foundation
Section titled “Foundation”| # | Document | What It Contains |
|---|---|---|
| 1 | design.md | Read this first. Sub-system structure, responsibilities, information ownership, dependency diagram, write/read path data flows, shared interface contracts (object key convention, presigned POST, CDN access control). Provides the structural context for all other documents. |
| 2 | requirements.md | 42 functional requirements (FR-001–FR-042), 21 non-functional requirements (NFR-001–NFR-021), and 7 user behavioral assumptions (UA-001–UA-007). Every requirement traces to source use cases and design decisions. |
| 3 | scenarios.md | PlantUML sequence diagrams and narratives for the 7 in-scope scenarios (S1–S7). Covers happy paths, error paths, and a cross-reference table mapping scenarios to use cases, decisions, and requirements. The diagrams use five sub-systems: User, SPA, BFF, Backend, and Storage. |
Sub-System Specifications
Section titled “Sub-System Specifications”Each sub-system document has four sections: Requirements, Interfaces, State, and Modules. They specify what each sub-system must do, the contracts between sub-systems, what state each sub-system manages, and the concrete modules to build or modify. See design.md for the structural overview and dependency relationships.
| # | Document | Sub-System | Key Content |
|---|---|---|---|
| 4 | spa-specification.md | SPA (React) | Input detection logic, ImageUploadDialog state machine, 13 new UI modules (from the UX Components spec), presigned POST upload orchestration, CDN rendering states. |
| 5 | bff-specification.md | BFF (Next.js) | Three new API routes (upload-url proxy, check-url reachability, fetch-url CORS fallback), SSRF protection spec, rate limiting, request/response contracts. |
| 6 | backend-specification.md | Backend (Operations / common-module) | Three new common-module classes (S3AssetService, AssetKeyGenerator, CdnUrlResolver), one new operations module (ImageUploadEndpoint), presigned POST generation, CDN URL validation via CdnUrlResolver (TD-14), testing strategy with MockAWS. |
| 7 | aws-specification.md | Storage (AWS Resources) | S3 bucket configuration (persistent, versioned, encrypted), CloudFront distribution with OAC, IAM presigning role, presigned POST policy conditions, three new CDK constructs, cross-stack exports. Breaks the “Storage” black box from the scenario diagrams into specific AWS resources. |
Security
Section titled “Security”| # | Document | What It Contains |
|---|---|---|
| 8 | cdn-access-control.md | For security auditor review. Threat model, solution design (CloudFront signed cookies), security properties, residual risks, cookie lifecycle, tenant switch analysis, key rotation and emergency revocation procedures. Covers TD-11 and TD-12. |
Synthesis
Section titled “Synthesis”| # | Document | What It Contains |
|---|---|---|
| 9 | oam-requirements.md | Operations, Administration, and Maintenance requirements organized by FCAPS: 6 fault management, 6 configuration, 4 accounting, 5 performance, and 15 security requirements (including CDN access control OAM-S-011–015). |
| 10 | risks-and-assumptions.md | 7 risks (HEIC support, orphaned objects, CORS breadth, presigned POST limits, cookie exfiltration, large files, SSRF), 6 assumptions (A-001 updated: images are sensitive), 5 migration concerns, and an out-of-scope tracker. |
| 11 | phasing.md | 11 implementation phases across 3 parallel tracks with dependency diagrams (design vs. deploy), entry/exit criteria per phase, critical path analysis, and verification gates. |
Process
Section titled “Process”| Document | What It Contains |
|---|---|
| observations.md | Structured observation log: 10 pre-execution observations (from the kickoff session) and 8 execution observations (from document production). Categorized as PROCESS, CONTENT, FRICTION, MISSING, or INSIGHT. Intended for consumption by an improvement-analyzer agent. |
Design Decisions
Section titled “Design Decisions”Design decisions TD-01 through TD-07 are recorded in the system design overview. Decisions TD-08 through TD-10 (made during authoring) are recorded in the project decision log.
Extension Points
Section titled “Extension Points”Image Resizing for Thumbnails
Section titled “Image Resizing for Thumbnails”The current design serves full-size images from the CDN and relies on CSS scaling for grid thumbnails. This is simple but wastes bandwidth — a 2 MB image loaded for a 50px grid cell. A server-side resizing capability would reduce bandwidth, improve grid load times, and lower CDN data-transfer costs.
Requirement: The system should be able to serve images at reduced dimensions for thumbnail contexts (grid cells, hover previews) without requiring the SPA to download the full-size original.
Options evaluated:
| Option | Mechanism | Pros | Cons |
|---|---|---|---|
| Lambda@Edge resize-on-demand | CloudFront origin-request trigger. Client requests ?w=100&h=100; Lambda fetches original from S3, resizes with Sharp, returns result. CloudFront caches the resized variant. | Integrates with existing CloudFront distribution and signed cookies. No pre-generation or extra storage. Each size variant cached independently. | Lambda@Edge must deploy to us-east-1. Cold-start latency on first request per size variant (~200-500ms). Adds a Lambda function to the AWS infrastructure. |
| Pre-generate thumbnails at upload time | S3 event notification triggers Lambda on upload. Generates fixed-size variants (<uuid>_thumb.jpg, <uuid>_medium.jpg) alongside the original. | Simplest read path — no on-the-fly processing. Predictable latency. | Additional storage (~2-3 variants per image). New size requirements need regeneration or backfill. Upload latency increases. |
| S3 Object Lambda | S3 Access Point triggers Lambda on GET to transform the object. | Per-request transformation without CloudFront changes. | Poor caching — each request triggers Lambda. Higher cost and latency at scale. Not designed for high-throughput read paths. |
| CSS scaling (current) | Serve full-size image; browser scales via CSS. | Zero infrastructure. Already working. | Wastes bandwidth. Slow grid loads on large images. Poor mobile performance. |
Recommendation: Lambda@Edge resize-on-demand is the strongest fit for this architecture. It works within the existing CloudFront distribution, preserves signed-cookie authentication, caches aggressively, and requires no changes to the upload path or storage layout. It should be implemented as an enhancement after the core upload capability is delivered.
Impact on current design: The SPA would append query parameters to CDN URLs
for thumbnail contexts (e.g., ?w=100&h=100&fit=cover). The
aws-specification.md would add a Lambda@Edge function
to the CloudFront distribution. No changes to the BFF or Backend.
Source Document Updates
Section titled “Source Document Updates”As part of this design session, several upstream documents were updated to reflect the resolution of TD-01 (fetch-and-store for external URLs):
- Entity Media Features — FR-0020 and Storage Model section
- Entity Media Use Cases — URL routing, clipboard HTML, confirm/persist paths
- Scoping — three rows updated
- Decision Log — SD-01 and SD-14 resolved
- Use Case Definition — open items table
Copyright: (c) Arda Systems 2025-2026, All rights reserved
Copyright: © Arda Systems 2025-2026, All rights reserved