---
title: "Acme Pulse — project README"
url: https://mdfy.app/SWys7jXa
updated: 2026-05-16T14:17:17.510Z
source: "demo-seed"
---
# Acme Pulse — project README

Acme Pulse is a landing-page builder for marketing teams. Build, A/B test, ship — all without engineering bandwidth.

## Stack

| Layer | Choice | Why |
|---|---|---|
| Frontend | Next.js 15 (App Router) | RSC + Cache Components |
| UI | Tailwind 4 + shadcn/ui | Atom-grade primitives, no design-system overhead |
| Auth + DB | Supabase | Magic link + RLS, no separate auth service |
| AI | Vercel AI Gateway | Provider failover, zero data retention |
| Email | Resend | Transactional + marketing |
| Hosting | Vercel | Same vendor as AI Gateway |

## Folder structure

```text
apps/web/
├── src/
│   ├── app/                # Routes (App Router)
│   ├── components/         # Atoms / molecules / organisms
│   ├── lib/                # Shared helpers (db, auth, ai)
│   └── styles/             # Tailwind config + globals
├── supabase/
│   └── migrations/         # Numbered SQL migrations
└── public/
```

## Local dev

```bash
pnpm install
cp .env.example .env.local       # fill SUPABASE_URL, OPENAI_API_KEY etc.
pnpm db:up                       # local supabase
pnpm dev                         # → http://localhost:3000
```

## 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`