Data Model
Glossary of Guinness's persistent entities. Organized following the Triangle Workflow into Wireframe, Design, and Code buckets, plus an Input bucket for pre-workflow artifacts and an Org-level bucket for identity and access control.
For physical schemas see development/database/postgresql/.
Input Bucket
| Entity | Description |
|---|---|
| Requirement | Pre-workflow artifact describing what the project should produce. Stored in multiple formats (uploaded files, linked documents). Provides product intent to WF2Des / WF2Code / Des2Code. |
Wireframe Bucket
The low-fidelity side of the triangle. "Wireframe" here refers to Figma wireframe data, not hand-drawn sketches.
| Entity | Description |
|---|---|
| Wireframe | Page-level wireframe artifact (Figma Data). One wireframe per page. |
| Structure | JSON representation of page structure derived from a wireframe. Serves as input to downstream conversions. |
| Detail Design | Document recording detailed decisions tied to a wireframe (copy, annotations, behavior notes). |
| Component (Wireframe) | Reusable wireframe component (Figma Data). |
Design Bucket
High-fidelity Figma designs.
| Entity | Description |
|---|---|
| Design | Page-level design artifact (Figma Data). Input to Des2Code; output of WF2Des / Code2Des. |
| Design Rule | Document describing visual and design-system rules that constrain generated designs. Input to WF2Des and the future Des2WF. |
| Component (Design) | Reusable design component (Figma Data). Matched against Code components during Des2Code. |
Code Bucket
High-fidelity code artifacts.
| Entity | Description |
|---|---|
| Generated Code | jsx / html page output produced by Des2Code or WF2Code. Tracked by status (pending / processing / completed / failed). |
| Code Component | Reusable component in jsx / html. Matched against Design components during Des2Code. |
| Matched Component | Mapping between a Design component and a Code component. Established by the AI matching pipeline. |
| Scraped Code | Code scraped from an existing live site (for site-renewal use cases in Code2WF / Code2Des). |
| Scraped Code Asset | Images, fonts, and other assets associated with scraped code. |
| Asset | General-purpose file asset (e.g., uploaded component screenshots). Stored in S3. |
Org-level Bucket
Identity, access control, and multi-tenant boundaries. Scaffolding that supports the workflow rather than workflow artifacts themselves.
| Entity | Description | Location |
|---|---|---|
| Organization | Top-level tenant. Owns projects, users, billing, and Figma tokens. | PostgreSQL |
| Project | Scope of a single product / site. Holds wireframes, designs, code, components, and generated code. | PostgreSQL |
| User | End user of the user-facing app. Belongs to one organization. | User PostgreSQL + Cognito app pool |
| Admin | 4D staff account. Operates api-admin / ui-admin. Separate pool and table from User. | PostgreSQL + Cognito admin pool |
| Role | Set of RBAC flags assigned to an Admin (admin_access, organization_access, project_access, user_access โ each NONE / READ / READ_WRITE). | PostgreSQL |
| Session | Server-side session record. Linked to a User or Admin. Used for token validation and logout. | PostgreSQL |
| Figma Token | User's Figma Personal Access Token (PAT). Required to import Figma files into Design / Wireframe entities. | PostgreSQL |
| MCP API Key | Long-lived API key for AI agents / automation systems calling the MCP server. Scoped per project. | User PostgreSQL |
| User-Project | Join row linking a User to an accessible Project. | User PostgreSQL |
How Buckets Connect During Conversion
| Tool | Input | Output |
|---|---|---|
| Des2Code (live) | Design (Component + Page) โ Matched Component | Generated Code |
| WF2Des (not started) | Wireframe + Detail Design + Structure + Design Rule | Design Page Variation |
| WF2Code (not started) | Wireframe + Detail Design + Structure + Code Component | Code Page |
| Des2WF (not started) | Design + Component | Wireframe + Structure |
| Code2Des (in development) | Code Page + Code Component | Design Page + Design Component |
| Code2WF (not started) | Code Page + Code Component | Wireframe + Structure + Wireframe Component |
Shared PostgreSQL Database
api-admin and api-user use PostgreSQL for admin accounts, sessions, workflow artifacts, and user identity. They retain separate Cognito pools for staff and end users; see ADR-0006 (decisions/0006-separate-cognito-pools).