System Need Analysis

This page captures the System Need Analysis (SA) viewpoint from the Arcadia method — defining what the system must do and what it interacts with, without prescribing how. It sits between operational scenarios (what users need) and logical architecture (how the system is decomposed).

System boundary

The system boundary is defined using BFO/IOF categories: what’s inside is composed of EngineeredSystems (IOF), Information Bearing Entities (IAO), and Processes (BFO). What’s outside includes external EngineeredSystems and Persons bearing Roles (CCO/BFO).

graph LR
    subgraph "External EngineeredSystems"
        SHOP[Shopify Admin API]
        DROP[Dropbox]
        GSSO[Google SSO]
    end

    subgraph "BluntDashboard (EngineeredSystem Composite)"
        UI[Dashboard UI]
        API[API Layer]
        BG[Background Jobs]
        DB[(Database — IBEs)]
        OBJ[(R2 — IBEs)]
    end

    subgraph "Persons bearing Roles"
        OPS[Ops / Creative / Fulfillment / Design]
    end

    OPS -->|browse, configure| UI
    UI -->|HTTP| API
    API -->|read/write| DB
    API -->|enqueue| BG
    BG -->|read/write| DB
    BG -->|upload/archive| OBJ
    BG -->|bulk query| SHOP
    BG -->|download assets| DROP
    BG -->|write metafields| SHOP
    GSSO -->|JWT assertion| API

Inside the system (EngineeredSystems + IBEs)

[IOF: EngineeredSystem | IAO: Information Bearing Entities (persistent storage)]

• Dashboard React UI (Vite, shadcn/ui, React Query)
• API layer (Hono on Cloudflare Workers) — EngineeredSystem
• Background jobs (queue consumers + cron handlers) — EngineeredSystem
• PlanetScale PostgreSQL — IBEs carrying all persistent ICEs
• Cloudflare R2 — IBEs carrying design assets, JSONL archives, document artifacts
• In-app CSV import/export

Outside the system (external EngineeredSystems)

Dependency	Protocol	Direction	Auth	Ontological type
Shopify Admin API	GraphQL + REST	Read orders/products; write metafields	Permanent offline access token	External EngineeredSystem (IOF)
Dropbox	HTTPS (share links)	Read-only asset download	None (public share links, dl=1)	External EngineeredSystem (IOF)
Cloudflare Access	JWT header	Inbound auth gate	Google SSO	External EngineeredSystem (IOF)
Cloudflare Hyperdrive	TCP (pooled)	DB connectivity	Binding credential	EngineeredSystem (IOF)

Staff (Persons bearing Roles)

[CCO: Person | BFO: bears Role]

Role	BFO Type	Typical interactions
Operations	Role (BFO)	Configure objective specifications, trigger syncs, monitor health
Creative	Role (BFO)	Manage creative act reports, create plan specifications, classify tags
Design	Role (BFO)	Assigned to tags via agent role assignments for attribution
Fulfillment	Role (BFO)	Monitor fulfillment metrics, look up commercial transaction records

Data flows

Data entering the system

Source	Data	Method	Frequency	Ontological character
Shopify	Orders, line items, products, tags, vendors	GraphQL bulk ops + REST	Daily cron + manual	IBEs carrying Process Records + MaterialArtifact data
Dropbox	Design asset files (PNG, JPG, PDF, etc.)	HTTP download from share links	On-demand (staff-initiated)	IBEs carrying ICEs (design assets)
Staff (UI)	Combo logs, tag classifications, designer assignments, classification settings, export requests	HTTP POST / CSV upload	Interactive	ICEs, Objective Specifications, Agent Role Assignments

Data leaving the system

Destination	Data	Method	Ontological character
Shopify	custom.production_asset_url metafield (R2 URL for design assets)	REST PUT	IBE reference (pointer to R2-hosted ICE)
R2 → Staff	CSV exports, design assets	Download via R2 public URL	Document Artifacts + ICEs via IBEs
Dashboard UI	Performance metrics, tag analytics, combo logs, fulfillment stats, order lookups	HTTP GET (JSON)	Measurement Data, ICEs, Creative Act Reports, Process Records
Cloudflare Logs	Structured JSON logs, run history	Workers Logs + optional Logpush	ProcedureExecution status observations

Data ownership

Owner	Data	Ontological character
Shopify (source of truth)	Products, orders, inventory, base product data, fulfillment status	MaterialArtifact attributes, Process Records (commercial transactions)
BluntDashboard (system-owned)	Performance classifications, tag groups, designer assignments, combo logs/templates/suggestions, ingest run history, R2 assets	Nominal Classifications, ICE Collections, Agent Role Assignments, Creative Act Reports, Plan Specifications, Suggestion ICEs, ProcedureExecution Records
Staff (human-created)	Classification rules/thresholds, tag categorizations, combo definitions	Objective Specifications, Tag ICEs, Plan Specifications (authored by Persons bearing Roles)

Non-functional requirements

Performance

Requirement	Target	Measurement
CRUD endpoint latency	p99 < 200ms	Workers analytics
Daily sync duration	< 15 minutes	procedure_execution_record.process_completed_at - process_initiated_at
Mart freshness	< 2 hours stale	performance_measurement_dataset.last_refreshed
Search response	< 500ms	End-to-end including DB query

Reliability

Requirement	Target	Mechanism
Sync runs daily without intervention	100% scheduled	Cron Trigger + queue retry (3 attempts)
Transient failures don’t lose data	Retry + resume	Watermark-based restart; JSONL archived before parse
Poison messages don’t block queue	DLQ isolation	Dead-letter queue for unprocessable messages
Data is recoverable	R2 archives	Raw JSONL (IBEs) stored in R2 for replay

Availability

Requirement	Notes
Staff-hours availability	Internal tool — no 24/7 SLA required
Graceful degradation	Stale mart data is acceptable; sync will catch up
Rollback capability	DNS revert < 5 min; PlanetScale branch restore

Security

Requirement	Implementation
No unauthenticated endpoints	CF Access gate on all routes
No hardcoded credentials	Wrangler secrets + Worker bindings (no .env in code)
Single auth plane	CF Access with Google SSO (replaces dual Passport + Supabase Auth)
No RBAC in v1	All authenticated staff have equal access
Audit trail	procedure_execution_record tracks every sync; R2 archives raw data

Rate limits and safety boundaries

Shopify API

Constraint	Value	Design response
GraphQL cost budget	50 pts/sec restored, ~1000 pt bucket	Bulk operations for high-volume reads
Bulk operation concurrency	1/shop (API < 2026-01), 5/shop (>= 2026-01)	Queue orchestration with retry on “already running”
REST pagination	250 items/page	Cursor-based pagination
Bulk op result retention	7 days	Download promptly after completion

PlanetScale

See PlanetScale Constraints for the full table. Key limits:

Constraint	Value	Design response
Rows per query	100k	Cursor-based pagination
Rows per statement	100k	Chunked batch writes
Transaction timeout	20s	Short, independent transactions

Upload limits

Constraint	Value
CSV combo import	2 MB
Template import	3 MB
Asset file types	PNG, JPG, JPEG, GIF, WEBP, SVG, ICO, BMP, PDF

Alerting thresholds

Condition	Severity	Threshold
Sync not completed	Critical	No completed run in 26 hours
Sync duration	Warning	> 15 minutes
DLQ messages	Critical	Any message in DLQ
Queue retries	Warning	> 10 retries/hour
API error rate	Critical	> 5% 5xx in 5-minute window
Mart staleness	Warning	> 2 hours since last refresh

See Observability for the full alerting strategy.