System Requirements Document for grid-app

1. Introduction

GRID (The Unified Product Handoff and Autonomous State Graph Engine) is a B2B platform for design and engineering teams that unifies product handoff across design tokens, backlog tickets, and production source code into one connected state graph. The product is delivered as a premium engineering command center — an obsidian, Apple Pro / Vercel-grade developer utility — in which a team's design, ticket, and code artifacts are spatially mapped, flattened into a searchable relational matrix, and reconciled through a compilation terminal.

The audience is power users: product engineers who move connected design, ticket, and source nodes and sync code upstream, and design systems leads who own Figma design token nodes and verify that design and code agree. GRID is delivered as an independent Kubernetes stack with a React frontend, a shared FastAPI backend, and MariaDB persistence.

This document is the System Requirements Document requested by Abdullah Alhuwaidi for the grid-app project.

Success Criteria

• A signed-in user can open the Drag-and-Drop Canvas Workspace and see three anchored node cards (Figma design token, Jira backlog, production source code) linked by dashed directional connectors on a 24px micro-dot grid.
• A user can drag a node card by its grab handle, and the card's position persists across view switches and later sessions.
• Switching between the three views is instantaneous, with no browser refresh and no loss of background state cache logs.
• The relational matrix flattens canvas nodes into searchable rows with Asset Identifier Name, Linked Infrastructure Context, and Environment Sync Badges (Active / Layout Drifted).
• The compilation terminal shows line-by-line processing logs and the CRITICAL VISUAL DRIFT callout with a working "[Reconcile Codebase & Patch AST]" action.
• Every readable label, number, and control remains fully inside the viewport at 375px, 768px, and 1280px.

2. System Overview

GRID is a single-page, authenticated B2B workspace with three reconciled interface views over one shared state graph:

1. THE DRAG-AND-DROP CANVAS WORKSPACE — an infinite 2D canvas with a white micro-dot grid, three anchored node cards, and animated dashed directional connectors.
2. THE HIGH-DENSITY RELATIONAL MATRIX — a full-bleed, searchable spreadsheet that flattens canvas node coordinates into columns with environment sync badges.
3. THE COMPILATION TERMINAL CONSOLE — a split-pane terminal with line-by-line processing logs above and an automated reconciliation engine below.

A fixed h-14 header holds the GRID wordmark, a segmented view-tab control, and a\x20\xe2\x8c\x98K / Ctrl K command palette bar. A w-80 detail panel anchors the right edge. The workspace ground is #0A0A0C with a muted radial ambient light.

Actors. Two active human personas — Product Engineer and Design Systems Lead — both self-enroll and sign in, and both operate all three views. The application backend executes durable workspace actions and code sync operations; MariaDB stores workspace state.

Delivery. React frontend, shared FastAPI backend, MariaDB, deployed as an independent Kubernetes stack.

Removed from scope

• Generic chatbot blocks.
• Rounded card shapes.
• Bright primary gradients.
• Messy layouts.

2a. Product Interpretation and Delivery Boundary

GRID is a first-party, application-owned product. All three interface views, the landing page, and self-service identity (Sign Up, Login) are owned and rendered by the GRID application. There is no provider-owned or external-only surface in the current scope; the Figma, Jira, and upstream-repository references are content shown inside GRID's own node cards and actions, not embedded third-party surfaces.

Access boundary: Landing is publicly reachable. Sign Up and Login are anonymously reachable identity surfaces. The three workspace views require a signed-in session, because canvas positions, matrix state, and terminal logs are durable, actor-specific state that must be resumed on return. Identity is application-owned and established through self-service enrollment; there is no invitation, provisioning, or role-based permission model in the current scope — both personas share the same workspace capabilities.

Current vs. future: everything specified in this document is current. No future-horizon capabilities are accepted.

2b. Source Content Inventory

Not applicable — no reference directive declares content_source.

2c. Page Content and Component Coverage

Landing

• Information/state: GRID wordmark (Space Grotesk, 56–72px), a one-line statement of what GRID is (unified product handoff and autonomous state graph engine for design and engineering teams), and a preview of the three reconciled views. Public, no session required.
• Primary actions: "Sign Up" (navigates to Sign Up), "Log In" (navigates to Login).
• Supporting actions: none beyond navigation.
• Domain entities: none persisted.
• Component responsibilities: h-14 header with wordmark and auth links; hero block on the #0A0A0C ground with the muted radial ambient gradient; a static preview of the canvas node cards and dashed connectors as imagery (not interactive).
• States: loading (skeleton for preview imagery); empty (n/a); success (rendered); error (preview imagery fails → text-only hero, links remain usable); recovery (retry link reloads preview).

Sign Up

• Information/state: self-service enrollment form. Anonymous access.
• Primary actions: submit enrollment (email + password) to create an application-owned identity.
• Supporting actions: link to Login for existing users.
• Domain entities: User identity (email, credential).
• Component responsibilities: form fields with inline validation; submit button with active:scale-[0.98] transition-all; error region.
• States: loading (submit disabled, spinner); empty (blank form); success (redirect to THE DRAG-AND-DROP CANVAS WORKSPACE); error (duplicate email or invalid input → inline message, form preserved); recovery (correct and resubmit).

Login

• Information/state: returning verification form. Anonymous access.
• Primary actions: submit credentials to reopen the signed-in workspace.
• Supporting actions: link to Sign Up.
• Domain entities: User identity.
• Component responsibilities: form fields; submit button with active:scale-[0.98] transition-all; error region.
• States: loading; empty; success (redirect to the last workspace view or the canvas); error (invalid credentials → inline message); recovery (retry).

THE DRAG-AND-DROP CANVAS WORKSPACE

• Information/state: infinite 2D canvas with a white micro-dot grid (background-size: 24px 24px, 12% opacity); three anchored node cards; animated dashed directional connectors (stroke: rgba(255,255,255,0.12), strokeDasharray: "4"); w-80 right detail panel; h-14 header with GRID wordmark, segmented view tabs, and\x20\xe2\x8c\x98K / Ctrl K palette bar. Requires login.
• Primary actions: drag a node card by its grab handle (cursor-grab on hover → cursor-grabbing on press); click "Sync to Upstream Repository" on Card C.
• Supporting actions: switch views via segmented tabs (instant, no refresh, state cache logs preserved); open command palette via\x20\xe2\x8c\x98K / Ctrl K.
• Domain entities: Canvas node (id, type, x, y, anchor), connector (from, to, direction), Figma design token node, Jira backlog node, source code node, sync status.
• Component responsibilities:
  • Card A — Figma Design Token Node (left anchored): absolute metadata indicator CheckoutForm.figma; embedded compass spinner graphic asset placeholder; glowing green synchronization status dot.
  • Card B — Relational Jira Backlog Node (centered): ticket key PROD-804: Refactor Payment State Hooks; high-priority flag label; team assignee identifier label.
  • Card C — Production Source Code Node (right anchored): code box with real syntax-highlighted React execution modules; primary highlight button "Sync to Upstream Repository".
  • Grab handle on each card with cursor state tracking.
  • Connector layer rendering animated dashed directional paths between cards.
  • Detail panel (w-80) showing the selected node's metadata.

• States: loading (grid + skeleton cards); empty (no nodes → grid with an empty-state note in the detail panel); success (cards positioned, connectors drawn, sync dot green); error (sync failure → inline error on Card C, dot turns non-green, retry available); recovery (retry sync; drag position restored from persisted state).

THE HIGH-DENSITY RELATIONAL MATRIX

• Information/state: full-bleed spreadsheet flattening canvas node coordinates into searchable columns: Asset Identifier Name, Linked Infrastructure Context, Environment Sync Badges (custom status modifiers Active and Layout Drifted). Requires login.
• Primary actions: search/filter rows; select a row to inspect in the w-80 detail panel.
• Supporting actions: switch views via segmented tabs; open command palette.
• Domain entities: matrix row derived from canvas node (asset identifier, linked infrastructure context, sync badge).
• Component responsibilities: search input; column headers; row renderer with smooth hover ground-color transition; badge component with Active and Layout Drifted modifiers; detail panel.
• States: loading (row skeletons); empty (no matching rows → empty-state message); success (rows rendered); error (fetch failure → retry banner); recovery (retry).

THE COMPILATION TERMINAL CONSOLE

• Information/state: split-pane container. Upper half: dark code-editor console streaming processing strings line-by-line (e.g., [SYSTEM] Vite Dev Server initialized on port 3000..., [SYNC] Database edge paths verified). Lower half: automated reconciliation engine showing the CRITICAL VISUAL DRIFT callout and the reconcile trigger. Requires login.
• Primary actions: click "[Reconcile Codebase & Patch AST]".
• Supporting actions: switch views; open command palette.
• Domain entities: terminal log line (timestamp, tag, message); drift finding (file, code bound, canvas bound).
• Component responsibilities: log stream renderer (mono #94A3B8); drift callout block with exact text "CRITICAL VISUAL DRIFT: The layout variable bounds inside CheckoutForm.tsx (220px) do not match the visual width modifications updated on the Infinite Canvas (280px)."; reconcile button that transitions to an emerald-500 highlight container on hover and uses active:scale-[0.98] transition-all.
• States: loading (log skeleton); empty (no logs → "awaiting system output"); success (logs stream; reconcile completes and appends a result line); error (reconcile failure → error line + retry); recovery (retry reconcile).

3. Functional Requirements

FR-1 — Dark luxury command center shell. As a Product Engineer or Design Systems Lead, I should see the workspace on a #0A0A0C ground with rgba(18,18,22,0.8) cards using backdrop-blur-xl, 1px rgba(255,255,255,0.06) borders, and a muted radial ambient gradient, so the tool reads as a premium engineering command center. Provenance: explicit. Acceptance: computed styles match the specified values; no rounded card shapes, bright primary gradients, or chatbot blocks appear.

FR-2 — Typography and layout limits. As a user, I should see h-14 header frames, w-80 detail panels, titles in #F3F4F6, and technical logs in mono-spaced #94A3B8, so layout stays uncrowded and legible. Provenance: explicit. Acceptance: header height and panel width match; title and log colors match.

FR-3 — Fluid segment controls. As a user, I should switch between the three views by clicking the segmented tabs, with an instantaneous active layout change and no browser refresh, and background state cache logs must not be dropped. Provenance: explicit. Acceptance: tab click swaps the active view within the motion budget; no full page reload; cached logs remain present after switching back.

FR-4 — Interactive node handles. As a user, I should see a distinct grab handle on each canvas node card, with cursor-grab on hover changing to cursor-grabbing on active press. Provenance: explicit. Acceptance: cursor changes on hover and press; dragging moves the card.

FR-5 — Keyboard shortcut matrix. As a user, I should see a global command palette bar shortcut indicator showing \xe2\x8c\x98 K or Ctrl K, and buttons should use active:scale-[0.98] transition-all for immediate mechanical feedback. Provenance: explicit. Acceptance: indicator renders the platform-appropriate shortcut; buttons scale on press.

FR-6 — Infinite micro-dot canvas. As a user, I should see an infinite 2D canvas with a crisp white micro-dot grid at background-size: 24px 24px and 12% opacity. Provenance: explicit. Acceptance: grid renders at the specified size and opacity and extends as the canvas pans.

FR-7 — Animated directional connectors. As a user, I should see thin animated directional edge paths (stroke: rgba(255,255,255,0.12), strokeDasharray: "4") connecting the blocks to map the team workflow. Provenance: explicit. Acceptance: connectors render between cards with dash animation and directional indication.

FR-8 — Card A Figma design token node. As a Design Systems Lead, I should see a left-anchored Figma design token node containing the absolute metadata indicator CheckoutForm.figma, an embedded compass spinner graphic asset placeholder, and a glowing green synchronization status dot. Provenance: explicit. Acceptance: all three elements render on Card A at its left anchor.

FR-9 — Card B Jira backlog node. As a Product Engineer, I should see a centered Jira backlog node tracking PROD-804: Refactor Payment State Hooks with high-priority flag and team assignee labels. Provenance: explicit. Acceptance: ticket key, priority flag, and assignee label render on Card B.

FR-10 — Card C source code node and sync. As a Product Engineer, I should see a right-anchored production source code node with a code box of real syntax-highlighted React execution modules and a primary button "Sync to Upstream Repository"; clicking it should sync the code upstream and show an observable result. Provenance: explicit. Acceptance: syntax highlighting renders; button triggers a backend sync; success or failure is shown on the card; failure offers retry.

FR-11 — Relational matrix. As a user, I should see a full-bleed spreadsheet that flattens canvas node coordinates into searchable columns: Asset Identifier Name, Linked Infrastructure Context, and Environment Sync Badges. Provenance: explicit. Acceptance: rows derive from canvas nodes; search filters rows; all three columns render.

FR-12 — Sync badges and row hover. As a user, I should see custom status modifiers Active and Layout Drifted on environment sync badges, and every row should change color smoothly on hover. Provenance: explicit. Acceptance: both badge variants render; row hover transitions ground color smoothly.

FR-13 — Split-pane terminal. As a user, I should see a split-pane console with terminal logs in the upper half streaming processing strings line-by-line (e.g., [SYSTEM] Vite Dev Server initialized on port 3000..., [SYNC] Database edge paths verified). Provenance: explicit. Acceptance: logs append line-by-line in the upper pane.

FR-14 — Reconciliation engine and drift callout. As a user, I should see, in the lower half, the exact callout "CRITICAL VISUAL DRIFT: The layout variable bounds inside CheckoutForm.tsx (220px) do not match the visual width modifications updated on the Infinite Canvas (280px)." with an adjacent primary trigger "[Reconcile Codebase & Patch AST]". Provenance: explicit. Acceptance: callout text matches exactly; button is adjacent.

FR-15 — Reconcile hover and action. As a user, I should see the reconcile button transition into an emerald-500 highlight container on hover, and clicking it should reconcile the codebase and patch the AST, producing an observable result. Provenance: explicit. Acceptance: hover applies emerald-500 container; click triggers backend reconciliation; result or failure is logged in the terminal; failure offers retry.

FR-16 — Self-service enrollment. As a new user, I should complete self-service enrollment on Sign Up before first use, so I own durable workspace state. Provenance: required_inference. Acceptance: valid submission creates identity and enters the workspace; invalid/duplicate shows inline error.

FR-17 — Returning verification. As a returning user, I should complete verification on Login before reopening protected workspace state. Provenance: required_inference. Acceptance: valid credentials restore the session and prior workspace state; invalid shows inline error.

FR-18 — Durable workspace state. As a user, I should have canvas node positions, matrix state, and terminal logs stored so they are available on return. Provenance: required_inference. Acceptance: after sign-out and sign-in, node positions and logs are restored.

FR-19 — Backend execution. As the system, I should execute durable workspace actions and code sync operations on the shared backend. Provenance: required_inference. Acceptance: sync and reconcile requests are served by the FastAPI backend and persisted in MariaDB.

4. User Personas

Product Engineer

• Product context: Works across design, backlog, and code artifacts and needs them to stay in agreement. Uses GRID as the command center for handoff.
• Primary goal: Keep the connected design → ticket → code chain accurate and push code changes upstream without leaving the workspace.
• Distinct responsibilities: Drags and positions node cards on the canvas; reads Card B's ticket PROD-804: Refactor Payment State Hooks with its priority and assignee; triggers "Sync to Upstream Repository" on Card C; searches the matrix for drifted assets; runs "[Reconcile Codebase & Patch AST]" in the terminal.
• Inputs/decisions: Decides when to sync code upstream; decides when to reconcile a drift finding.
• Interactions: Shares the workspace with the Design Systems Lead; both see the same canvas, matrix, and terminal state.
• Observable success: Sync completes with a visible result; drift is reconciled and confirmed in the terminal logs.

Design Systems Lead

• Product context: Owns Figma design token nodes and guards design-code agreement.
• Primary goal: Confirm that design tokens and code agree, and catch layout drift early.
• Distinct responsibilities: Inspects Card A's CheckoutForm.figma metadata and green sync dot; checks the matrix for Layout Drifted badges; reads the CRITICAL VISUAL DRIFT callout comparing 220px code bounds to 280px canvas bounds; authorizes reconciliation.
• Inputs/decisions: Decides whether a drift is a design change or a code defect before reconciling.
• Interactions: Relies on the Product Engineer's code sync; both operate the same views.
• Observable success: Drifted assets are identified and reconciled; the sync dot and badges reflect agreement.

5. Core User Flows

Flow A — First use (both personas)

1. User opens Landing (anonymous) and reads what GRID is.
2. User clicks Sign Up, enters email and password, and submits.
3. On success, the app creates the identity and opens THE DRAG-AND-DROP CANVAS WORKSPACE. On error (duplicate/invalid), an inline message appears and the form is preserved for correction.

Flow B — Returning use

1. User opens Login (anonymous), enters credentials, and submits.
2. On success, the app restores the session and prior workspace state (node positions, logs) and opens the last view. On error, an inline message appears and the user retries.

Flow C — Product Engineer: position nodes and sync code

1. In THE DRAG-AND-DROP CANVAS WORKSPACE, the engineer sees Cards A, B, C anchored left, center, right on the 24px dot grid, linked by dashed connectors.
2. Engineer hovers a card's grab handle (cursor-grab), presses (cursor-grabbing), and drags it to a new position; the card and its connectors follow.
3. Engineer clicks "Sync to Upstream Repository" on Card C; the backend performs the sync.
4. Success: Card C shows a success result and the sync dot stays green. Failure: Card C shows an inline error and a retry action; the engineer retries.
5. Engineer switches to THE HIGH-DENSITY RELATIONAL MATRIX via the segmented tabs — instant, no refresh, logs preserved — and searches for the asset to confirm its badge.

Flow D — Design Systems Lead: detect and reconcile drift

1. In THE COMPILATION TERMINAL CONSOLE, the lead reads the upper terminal logs streaming line-by-line.
2. The lower reconciliation engine shows the CRITICAL VISUAL DRIFT callout (CheckoutForm.tsx 220px vs. canvas 280px).
3. Lead hovers "[Reconcile Codebase & Patch AST]"; it fills with emerald-500.
4. Lead clicks it; the backend reconciles the codebase and patches the AST.
5. Success: a result line appends to the terminal and the drift clears. Failure: an error line appends with a retry action; the lead retries.
6. Lead switches to THE HIGH-DENSITY RELATIONAL MATRIX to confirm the asset badge now reads Active.

Flow E — Matrix inspection (both personas)

1. User opens THE HIGH-DENSITY RELATIONAL MATRIX; rows flatten canvas nodes into Asset Identifier Name, Linked Infrastructure Context, and Environment Sync Badges.
2. User types in search to filter rows; hovering a row smoothly changes its ground color.
3. User selects a row to inspect it in the w-80 detail panel. Empty search results show an empty-state message.

6. Visuals Colors and Theme

Muse: Rasmus Andersson. Headline: Systematic product craft on an obsidian ground.

Palette (dark mode):

• Background: #0A0A0C
• Surface: #121216 at 80% opacity with backdrop-blur-xl
• Text: #F3F4F6
• Primary (sync signal): #34D399
• Accent (active tab, reconcile button): #E8FF5A
• Muted: #94A3B8
• Borders: rgba(255,255,255,0.06)
• Emerald-500 hover container: #10B981
• Ambient: radial-gradient(ellipse at top, rgba(115,115,115,0.05), transparent)

Typography: Headings Space Grotesk, 500 weight, -0.02em tracking. Body Inter Tight. Micro-labels uppercase 11px, 0.12em tracking. Modular scale 1.25: 72/56/40/28/20/16/14/12; display 40px mobile → 72px desktop.

Shape: Sharp 1px rules, 4/8-pt grid, corners 4px or square. No rounded cards, no gradients except the muted radial ambient.

Layout: Fixed h-14 header (wordmark, tab segment,\x20\xe2\x8c\x98K palette bar); w-80 right detail panel; canvas/matrix/console fill the rest.

7. Signature Design Concept

The first screen is the live canvas view. A 56–72px Space Grotesk GRID wordmark sits at the left of the h-14 header, beside a segmented tab control and a\x20\xe2\x8c\x98K palette bar with a hairline top rule. Below, on the #0A0A0C ground with a soft radial light at the top, three node cards span the field left-to-right on the 24px white dot grid at 12% opacity, linked by dashed rgba(255,255,255,0.12) connectors. A w-80 detail panel anchors the right edge. The interface is the image: no marketing hero, no gradient blobs — just the working command center.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: restrained Hero Dimensionality: flat

Landing Hero Motion Brief: Focal subject is the canvas node field (three cards + dashed connectors on the dot grid). Input→transformation→outcome: on load, connectors draw in with their dash animation and cards settle into their anchors; on tab switch, the active view swaps instantly (120–200ms) without reload. Motion vocabulary: fast, functional, 120–200ms transitions; grab handles show cursor-grab → cursor-grabbing; buttons use active:scale-[0.98]; reconcile button fills emerald on hover. Composed first frame: wordmark, tabs, palette bar, three anchored cards, dashed connectors, right detail panel. Reduced-motion state: connectors render static (no dash animation), cards appear in place, view switches remain instant with no transition.

9. Non-Functional Requirements

• NFR-1 (explicit): Independent Kubernetes deployment.
• NFR-2 (explicit): No generic chatbot blocks, rounded card shapes, bright primary gradients, or messy layouts.
• NFR-3 (explicit): h-14 header frames and w-80 detail panels.
• NFR-4 (explicit): View switches must not refresh the browser or drop background state cache logs.
• NFR-5 (explicit): Buttons use active:scale-[0.98] transition-all.
• NFR-6 (explicit): Motion 120–200ms; restrained tempo.
• NFR-7 (required_inference): Readable text and controls stay whole at 375px, 768px, and 1280px, wrapping or scaling (e.g., clamp()) to fit; nothing covers them.
• NFR-8 (required_inference): prefers-reduced-motion yields a usable static arrangement.
• NFR-9 (required_inference): Durable workspace state persisted in MariaDB; sessions protected behind login.

10. Tech Stack

• Frontend: React (single-page app) with the specified design system (Space Grotesk, Inter Tight, Tailwind-style utilities including backdrop-blur-xl, active:scale-[0.98]).
• Backend: shared FastAPI process serving application APIs and domain modules (workspace state, sync, reconcile).
• Database: MariaDB for application-owned persistent data (users, canvas nodes, connectors, logs, drift findings).
• Deployment: independent Kubernetes stack (docker-compose for local parity).

11. Assumptions and Constraints

• A-1: Both personas share identical workspace capabilities; no role-based permissions are specified.
• A-2: Identity is application-owned self-service (Sign Up / Login); no invitation or provisioning flow.
• A-3: The Figma, Jira, and upstream-repository references are content within GRID's own cards and actions, not embedded third-party surfaces.
• A-4: The three views share one state graph; switching preserves state.
• C-1: Independent Kubernetes deployment is mandatory.
• C-2: Design constraints (palette, fonts, surfaces, no rounded cards/gradients/chatbots) are binding.

12. Glossary

• State graph: The connected model of design tokens, tickets, and source code nodes and their directional links.
• Node card: A spatial block on the canvas representing a Figma token, Jira ticket, or source code artifact.
• Connector: An animated dashed directional path linking node cards.
• Relational matrix: The flattened, searchable spreadsheet view of canvas nodes.
• Environment Sync Badge: A status modifier (Active or Layout Drifted) on a matrix row.
• Visual drift: A mismatch between code layout bounds and canvas visual bounds.
• AST patch: The reconciliation action that aligns code with canvas state.
• \xe2\x8c\x98K / Ctrl K: The global command palette shortcut.