--- mw_bundle: 1 id: p_mdtSk0 title: "Cross-tool dev workflow" url: https://memory.wiki/b/p_mdtSk0 document_count: 7 updated: 2026-05-24T17:26:32.977Z analysis_generated_at: 2026-05-16T14:21:51.031Z analysis_stale: true source: "memory.wiki" --- # Cross-tool dev workflow > Acme Pulse, a fictional landing-page builder. The seven docs in this bundle are the project's living context — README, auth pattern, DB schema, API conventions, UI patterns, decision log, open questions. Paste this bundle URL into Cursor's .cursor/rules and Claude Code's CLAUDE.md; both AI tools now have the same project memory and stay in sync as the docs update. This is the wedge use case mdfy's URL-as-memory thesis is built around. > ⚠ _Analysis may be stale — one or more member docs were edited after the last analysis run. Re-run the canvas to refresh._ ## Summary This collection represents a comprehensive technical documentation suite for Acme Pulse, a landing page builder built on Next.js and Supabase. The documents establish a complete development framework from architectural decisions and UI patterns to database design and API conventions. The project emphasizes vendor consolidation, developer experience, and security-first design through Row Level Security, creating a cohesive full-stack application architecture. ## Themes - Full-Stack Architecture - Vendor Consolidation Strategy - Security-First Design - Developer Experience Optimization ## Cross-document insights - The project demonstrates a strategic bias toward integrated solutions over best-of-breed tools, consistently choosing vendors that provide multiple services (Supabase for auth+DB, Vercel for hosting+AI) to reduce operational complexity. - Row Level Security is positioned as both a security pattern and an architectural decision that eliminates the need for separate authorization services, showing how database-native features can simplify system design. - The documentation reveals tension between comprehensive patterns (detailed ADRs, strict component hierarchies) and pragmatic shortcuts (open questions, vendor lock-in acceptance), suggesting a mature approach to technical debt management. - The atomic design implementation creates explicit import restrictions between component layers, which is unusual and suggests the team has experienced problems with circular dependencies or component coupling in previous projects. ## Key takeaways - Acme Pulse is architected around vendor consolidation and integrated solutions (Supabase, Vercel) to minimize operational complexity while maintaining security through database-native Row Level Security. - The project establishes comprehensive development patterns from atomic design component hierarchy to ADR-based decision documentation, showing mature engineering practices for a greenfield application. - Strategic technical debt is explicitly acknowledged and managed through open questions and decision deferral, with clear criteria for when to revisit choices (revenue thresholds, scale limits). ## Open questions / gaps - Testing strategy and patterns are completely absent - no mention of unit tests, integration tests, or end-to-end testing approaches - Monitoring, logging, and observability practices are not documented despite mentioning Vercel AI Gateway's observability features - Deployment and CI/CD pipeline details beyond basic Vercel deployment are missing - Error handling and debugging patterns for the client-side application are not covered - Internationalization implementation details are acknowledged as open questions but lack research or spike work ## Notable connections - **doc:SWys7jXa** ↔ **doc:SrgEHFCI** — The README references the decision log as the source of truth for 'why we chose X' architectural questions - **doc:SrgEHFCI** ↔ **doc:mjpt9oz8** — The Supabase decision in the ADR is implemented through the detailed RLS authentication patterns - **doc:wp12y7sM** ↔ **doc:LhYW7tc1** — Form validation patterns in UI connect directly to the API's error handling and validation schemas - **doc:HsxL91R7** ↔ **doc:mjpt9oz8** — Database schema supports the RLS policies and authentication patterns with organization_members table structure - **doc:ir0K6-u2** ↔ **doc:SrgEHFCI** — Open questions represent future decisions that will extend the ADR log once research and interviews are completed - **doc:LhYW7tc1** ↔ **doc:mjpt9oz8** — API authentication methods directly implement the Supabase JWT and token-based auth patterns described in the auth document ## Concepts (this bundle) - **Tailwind Design Tokens** - **Atomic Design** - **ADR Documentation** - **Row Level Security** - **Vendor Consolidation** - **Cursor Pagination** - **Progressive Enhancement** ## Concept relations - **Atomic Design** ↔ **Progressive Enhancement** — enables - **Row Level Security** ↔ **Vendor Consolidation** — supports ## Documents ### 1. [Acme Pulse — project README](https://memory.wiki/SWys7jXa) Acme Pulse is a landing-page builder for marketing teams. Build, A/B test, ship — all without engineering bandwidth. *sections:* Stack: | Layer | Choice | Why | | Folder structure: text | Local dev: bash | Deploy: main → Vercel preview; production branch → mdfy.app; Migrations run via supabase db push --include-all (NOT auto on deploy) | Where to look when: Auth flow questions → docs/auth.md (this bundle); DB / migration questions → docs/db-schema.md; API endpoint conventions → docs/api-conventions.md; UI component patterns → docs/ui-patterns.md; "Why we chose X" → docs/decision-log.md; Open questions / parking lot → docs/open-questions.md; … ### 2. [Auth pattern — Supabase Auth + RLS](https://memory.wiki/mjpt9oz8) Same vendor as DB → JWT `sub` ↔ `auth.users.id` join is native (no email-lookup roundtrip) RLS lives next to the data — auth and authz are one table read away Magic link + Google + GitHub out of the box Free up to 50k MAU; matches our pre-revenue runway *sections:* Why Supabase Auth (not Clerk / NextAuth / Auth0): Same vendor as DB → JWT sub ↔ auth.users.id join is native (no email-lookup roundtrip); RLS lives next to the data — auth and authz are one table read away; Magic link + Google + GitHub out of the box; Free up to 50k MAU; matches our pre-revenue runway | RLS policies (per role): sql | Session handling: Server components → createServerClient with cookie store; Client components → @supabase/ssr browser client; API routes → verify the JWT with verifyAuthToken (see lib/verify-auth.ts); Anonymous edits → cookie-grouped anonymousid until first sign-in | … ### 3. [DB schema notes](https://memory.wiki/HsxL91R7) `users` — owned by Supabase Auth `organizations` — top-level tenant `organization_members` — (user_id, organization_id, role) `pages` — a landing page `page_versions` — append-only history per page `page_blocks` — section-level content (headline / hero / cta / form / etc.) `ab_tests` — variant assignment + outcome *sections:* Core tables: users — owned by Supabase Auth; organizations — top-level tenant; organizationmembers — (userid, organizationid, role); pages — a landing page; pageversions — append-only history per page; pageblocks — section-level content (headline / hero / cta / form / etc.); …; abtests — variant assignment + outcome; … | Migration naming: NNNdescriptivename.sql where NNN is zero-padded. Don't reuse | Views vs functions: View when the result is a deterministic projection of base tables. No side effects.; Function (PL/pgSQL) when you need parameters or row-by-row logic.; Avoid materialised views for now — refresh complexity > query speed gain at our scale. | … ### 4. [API conventions](https://memory.wiki/LhYW7tc1) The API uses versioned paths, HTTP verbs mapped to standard operations with soft deletes by default, and consistent error shapes with machine codes. Authentication supports JWT tokens for signed-in users and per-document capability tokens for anonymous edits, with rate limiting at 60 requests per minute and cursor-based pagination capped at 200 rows per response. *sections:* URL shape: /api/v1/ for stable endpoints. Versioned via the path. Sub-resources nest: /api/v1/pages//blocks. | HTTP verbs: GET — idempotent read; POST — create; PATCH — partial update (default for edits); PUT — full replace (rare, use sparingly); DELETE — soft delete (sets deletedat); pass ?permanent=true for hard delete | Error shape: Every error response: | Authentication: Two paths, in order of precedence: | Rate limiting: Sliding window, IP-based, 60 req/min default. Override per-route in middleware.ts. Returns 429 with Retry-After header. | Pagination: Cursor-based, not offset. ?cursor=&limit=20. Response includes nextCursor (or null if last page). | … ### 5. [UI patterns](https://memory.wiki/wp12y7sM) Design tokens live in `globals.css` as CSS variables: `--background`, `--accent`, `--text-primary`, etc. Use `var(--...)` everywhere. Don't hardcode hex. Dark mode via `[data-theme="dark"]` on ``. Tokens get re-bound at the document root. *sections:* Tailwind 4 conventions: Design tokens live in globals.css as CSS variables: --background, --accent, --text-primary, etc.; Use var(--...) everywhere. Don't hardcode hex.; Dark mode via [data-theme="dark"] on . Tokens get re-bound at the document root. | Component organization: text | Form validation: Zod schemas live next to the form. useForm from React Hook Form. | Loading states: Prefer boundaries with skeletons over conditional | Empty states: Every list view has an empty state with: icon + 1-line copy + 1 | … ### 6. [Decision log](https://memory.wiki/SrgEHFCI) ADR-style records. Append-only — never edit a decision, append a new one that supersedes. *sections:* ADR-001 — Next.js App Router over Pages Router (2026-03-04): Context. Greenfield project. Both routers are stable. | ADR-002 — Supabase over Neon + Clerk (2026-03-04): Context. Need DB + auth. | ADR-003 — Resend over SendGrid (2026-03-12): Context. Transactional + marketing email. | ADR-004 — pgvector over Pinecone (2026-04-02): Context. Need vector similarity for AI features. | ADR-005 — Tailwind 4 over CSS Modules (2026-04-08): Context. Component styling. | ADR-006 — Vercel AI Gateway over direct Anthropic SDK (2026-04-22): Context. Multiple AI providers for failover. | ADR-007 — Postgres over DynamoDB (2026-05-08): Context. Block-level content with complex relationships. ### 7. [Open questions](https://memory.wiki/ir0K6-u2) Things we're carrying. Not decisions — placeholders. *sections:* Pricing model: Three candidates: | Webhook delivery semantics: We emit webhooks on page.published, page.updated, form.submitted.; At-least-once (current) — receivers must dedupe; Exactly-once — requires distributed ledger / message ID tracking; Practical answer is probably at-least-once + a webhookid header for receiver-side dedup | i18n strategy: Currently English-only. Korean is the next likely market based on inbound interest. Options: | Per-block vs per-page versioning: Currently versioning at the page level. Marketing users edit one | Cron jobs ownership: Right now cron lives in api/cron/ routes triggered by Vercel _Digest view — follow any link above to fetch that doc's full markdown. Add `?full=1` to this URL for the concatenated payload._