Architect a design review platform that links Figma artifacts, Storybook previews, and…
- User
Architect a design review platform that links Figma artifacts, Storybook previews, and Git diffs while capturing async approvals and audit trails.
Assistant
The user wants an architecture for a "design review platform" that integrates several key components: Figma (design), Storybook (UI components/previews), and Git (code changes). The core function is to facilitate asynchronous design reviews, including approvals and maintaining an audit trail.
1. Deconstruct the Requirements:
- Integrations:
- Figma: Needs to link to specific frames/files. Ideally, capture snapshots or deep links.
- Storybook: Needs to embed or link to live component previews.
- Git: Needs to parse diffs (pull requests/commits) to show code changes associated with design changes.
- Core Functionality:
- Linking: The ability to associate a Figma frame with a specific Storybook story and a specific Git PR/commit.
- Async Approvals: A workflow system where stakeholders (designers, devs, PMs) can review and sign off without being online simultaneously.
- Audit Trails: A log of who approved what, when, and what version of the design/code was approved.
2. High-Level Architecture Strategy:
I need a web-based application (likely a SaaS product or internal tool). I'll use a standard 3-tier architecture (Client, API, Data) plus external integrations.
- Frontend: A React/Next.js app. It needs a sophisticated dashboard and a "Review Canvas" where the user sees the linked artifacts side-by-side.
- Backend: A Node.js/Python service (or microservices) to handle the logic, API requests, and webhooks from Figma/GitHub/GitLab.
- Database: Relational (Postgres) for structured data (reviews, users, links) and NoSQL/S3 for storing snapshots or large JSON blobs (audit logs).
- Integrations (The "Glue"):
- Figma Plugin: Essential for initiating the review from the design tool.
- Git Webhooks: To trigger updates when a PR is updated.
- Storybook iframe/embed: To render the live component.
3. Detailed Component Design:
-
The "Review Entity": This is the central object. It represents a specific unit of work to be reviewed.
- Fields: ID, Figma Link, Storybook URL, Git PR URL, Status (Pending, Approved, Changes Requested), Version Hashes.
-
Workflow - Creating a Review:
- Designer selects a frame in Figma.
- Plugin opens -> Designer pastes Storybook link and Git PR link.
- Backend verifies links.
- Backend fetches a snapshot from Figma (for the audit trail, in case the design changes later) and stores it.
- Review is created and notifications sent.
-
Workflow - Conducting a Review:
- Reviewer opens the Review.
- UI has three columns/panes:
- Design: The Figma image (snapshot or live embed).
- Implementation: The Storybook iframe (interactive).
- Code: The Git diff view (syntax highlighted).
- Reviewer compares Design vs. Implementation.
- Reviewer adds comments (linked to specific coordinates or code lines?).
- Reviewer clicks "Approve".
-
Audit Trail & Approvals:
- Need an immutable ledger.
- Store:
{ timestamp, user_id, action: "APPROVED", artifact_versions: { figma_version: "v1", git_sha: "abc" } }. - This ensures that when design changes after approval, the approval is flagged as outdated (stale).
4. Key Challenges & Solutions:
- Syncing Versions: The biggest headache. A Figma file is constantly changing. A Git PR is constantly changing.
- Solution: Pinning. When a review is created, pin to a specific Figma commit/version and a specific Git commit SHA. If the designer publishes a new version in Figma, the platform should detect it and mark the previous review as "Stale".
- Security: Accessing private Git repos and private Figma files. Need robust OAuth implementations.
- Storybook Accessibility: If Storybook is running locally or behind a VPN, the platform can't see it.
- Solution: Require Storybook to be hosted (e.g., Chromatic, Vercel, or static S3 bucket) or use a proxy/agent.
5. Structuring the Response:
I will structure the architecture proposal as follows:
- System Overview: High-level goals and the core concept.
- Core Data Model: How we represent a "Review" and the links.
- Architecture Diagram (Mental Model): Frontend, Backend, Integrations.
- Key Flows:
- Ingestion (Creation): How data gets in.
- The Review Interface: How humans see it.
- Webhooks/Sync: Keeping data fresh.
- Technical Stack Recommendations: Specific tools to use.
- Deep Dive on Audit Trail: The immutable aspect.
- Scalability & Edge Cases: Handling the "dynamic" nature of the inputs.
6. Refining the Design:
- Figma Plugin: Crucial. Designers shouldn't have to leave Figma to create the "link".
- Visual Diffing: A "nice to have" but highly valuable feature. Visual regression testing (like Percy or Chromatic) could be integrated. I'll mention this as an advanced feature.
- The "Golden State": The goal is to ensure Figma == Storybook == Git.
7. Drafting the Content (Self-Correction during drafting): Initial thought: Just store links. Correction: Links rot. If the Figma file is deleted or the Git branch is squashed, the audit trail is broken. Refinement: The system must take snapshots/screenshots at the moment of approval for the audit trail to be legally/compliantly useful.
Let's build out the "Review Canvas" concept. It needs to be a split-screen comparator.
- Left: Figma (Static Snapshot + Link to Live)
- Right: Storybook (Live Iframe)
- Bottom: Git Diff (Text diff)
Or maybe tabbed? No, side-by-side is better for design review.
8. Final Polish: Organize by layers: Presentation, Application, Data, Infrastructure. Add a section on the specific "Linking Strategy" (Semantic Linking).
Let's proceed with generating the response based on this structure. This architecture outlines a system designed to bridge the gap between Design, Development, and Product Management. We will call this platform "Align".
The core challenge here is State Synchronization. Figma is a living document, Storybook is a component build, and Git is a linear history. The platform must pin these three moving targets to a specific point in time to facilitate a coherent review.
1. High-Level Architecture Diagram
The system follows an Event-Driven Microservices Architecture. This allows the ingestion of webhooks from Git/GitHub/GitLab and Figma without blocking the user interface.
graph TD subgraph "Client Layer" UI[React/Web App] FigPlugin[Figma Plugin] Ext[Browser Ext (Storybook)] end subgraph "API Gateway" GW[GraphQL / REST Gateway] end subgraph "Services" Ingest[Ingestion Service (Webhooks)] Core[Core Review Service] Snapshot[Snapshot Worker] Audit[Audit & Compliance Service] end subgraph "Data Layer" DB[(PostgreSQL)] Cache[(Redis)] Store[Object Store (S3/MinIO)] end subgraph "External Integrations" GitHub[Git Providers] Figma[Figma API] Storybook[Storybook CI/CD] end UI --> GW FigPlugin --> GW Ext --> GW GW --> Core GitHub -->|Webhook| Ingest Figma -->|Webhook| Ingest Storybook -->|Build Event| Ingest Ingest --> Core Core --> DB Core --> Snapshot Snapshot --> Store Audit --> DB
2. The Core Data Model
The database (PostgreSQL) must be normalized to handle the relational complexity of artifacts.
Key Entities:
- ReviewRequest: The parent object. Contains the
status(Draft, Pending Review, Approved, Changes Requested). - Artifact: Links to external resources.
type: ENUM (FIGMA, STORYBOOK, GIT_DIFF)external_id: The API ID (e.g., Figma Node ID, GitHub PR ID).version_hash: Critical for immutability (e.g., Git SHA, Figma Last Edited timestamp).
- ArtifactSnapshot:
- To ensure audit trails survive if the external link breaks or changes, we store static versions.
image_url: S3 link to a PNG of the Figma frame.html_diff: A static HTML file representing the code diff.
- Approval: Records the user, timestamp, and specific artifact versions they approved.
- Comment: Threaded discussions linked to specific X/Y coordinates on an ArtifactSnapshot.
3. The "Linking" Strategy (The Hard Part)
Linking these disparate technologies requires a Semantic ID Strategy.
A. The "Golden Identifier"
We cannot rely on random IDs. The system needs a shared taxonomy.
- Strategy: Use the Storybook Story Name or Component Name as the "Source of Truth."
- Implementation:
- Figma: The Figma plugin forces the designer to tag a Frame with the corresponding Storybook Story Name (e.g.,
atoms/Button/Primary). - Storybook: The Story name matches naturally.
- Git: The platform scans the PR files. If a file changes
Button.tsx, it looks upatoms/Buttonin its database to auto-link the PR to the relevant Design Review.
- Figma: The Figma plugin forces the designer to tag a Frame with the corresponding Storybook Story Name (e.g.,
B. Pinning States (Immutability)
- Figma: Designs change constantly. When a Review is created, the platform uses the Figma API to export the frame as a PNG/SVG and stores it in S3. The review references the file, not just the live Figma link.
- Storybook: We utilize the Storybook
versionparameter or Chromatic build ID. The platform links to a specific static build, not thelatestbranch.
4. Component Breakdown
A. The Ingestion Service (Webhooks)
This is the entry point for automation.
- Git Webhook: Listens for
PullRequestevents.- Action: Parses the git diff. Identifies changed files. Auto-creates a "Review Request" if a matching Figma artifact exists, or updates the status of an existing review.
- Figma Webhook: Listens for
FILE_SAVEor specific plugin events.- Action: If a frame is tagged "Ready for Review", it triggers the Snapshot Worker.
B. The Snapshot Worker
Responsible for capturing the "truth" at that moment.
- Git: Runs
git diffinternally or uses the GitHub API to fetch the patch. - Storybook: Uses Puppeteer/Playwright to screenshot the "Before" and "After" components if a visual diff is required.
C. The Audit Service
An append-only log service.
- Every action (View, Comment, Approve, Reject, Update Link) is written to a separate table (
audit_logs). - This table is optimized for writes, not reads. It serves as the compliance ledger.
5. User Workflow (The Review Cycle)
-
Initiation:
- Designer selects a frame in Figma via the custom plugin.
- They tag it with the component name (e.g.,
ProfileCard). - They click "Submit for Review."
-
Linking:
- The backend receives the Figma payload.
- It queries the database: "Do we have a Storybook build or Git branch associated with
ProfileCard?" - If a matching Git branch exists (detected via naming convention like
feat/profile-card), it auto-links them.
-
The Review Interface:
- The Reviewer sees a split view:
- Left: The Figma Snapshot (Static Image).
- Middle: The Live Storybook Iframe (Interactive).
- Right: The Git Diff (Code View).
- Feature: Visual Diff Mode. The platform overlays the Figma Snapshot (semi-transparent) on top of the Storybook iframe to check pixel-perfect alignment.
- The Reviewer sees a split view:
-
Async Approval:
- Approver clicks "Approve."
- The Audit Service records:
{ user: "Lead Dev", action: "APPROVE", artifact_versions: { figma: "v123", git_sha: "a1b2" } }. - Automation: Once all required columns (Design, Dev, PM) have approved, the system posts a comment on the Git PR (e.g., "Design Review Passed") and removes the
blockedlabel.
6. Technical Stack Recommendation
- Backend: Node.js (NestJS) or Go. Node is preferred for easy integration with the JavaScript-based Figma Plugin API and Storybook ecosystem.
- Database: PostgreSQL.
- Queue: Redis (BullMQ) for handling the Snapshot processing and webhook backpressure.
- Storage: AWS S3 (for artifact snapshots).
- Frontend: React + TypeScript. Utilizing libraries like
react-diff-viewerfor code andreact-annotationfor Figma markup.
7. Audit & Compliance Features
To satisfy strict audit requirements (e.g., SOC2, HIPAA):
- Cryptographic Hashing: When a snapshot is taken (Figma image or Code Diff), generate a SHA-256 hash. Store this hash in the Audit Log.
- Why? Proves that the artifact reviewed is exactly the same as the artifact that was deployed (assuming you trace the git SHA to deployment).
- Immutable Approvals: An approval object cannot be deleted, only "revoked" (which creates a new audit event).
- Identity Federation: Integrate with SSO (Okta/Auth0) to ensure the person clicking "Approve" is definitely who they say they are.
Summary of Innovation
The innovation of this platform lies in Decoupled Versioning. It acknowledges that Figma, Git, and Storybook version differently. By introducing an intermediate "Snapshot" layer that captures the state of all three simultaneously, you create a stable foundation for asynchronous audit and approval.
- Integrations:
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.