diff --git a/README.md b/README.md index 85b06fd..e3cc1f0 100644 --- a/README.md +++ b/README.md @@ -1,95 +1,91 @@ # Lively Forms -Lively Forms is a Typeform-inspired conversational form builder built with Next.js, Auth.js, Prisma, PostgreSQL, Tailwind, Framer Motion, and dnd-kit. +Lively Forms is a conversational form builder inspired by Typeform. It lets creators build multi-step forms, publish them publicly, collect anonymous responses, and review/export submissions across personal or shared organization workspaces. + +## Features + +### Form building +- Master-detail form builder with block reordering +- Supported block types: + - text + - short text + - long text + - single choice + - multiple choice + - number + - link + - agreement + - date +- Required questions +- Type-specific validation: + - text regex validation + - number min/max and integer-only rules + - link validation + - date validation + - agreement validation +- Publish / unpublish controls +- Shareable public form slugs +- Custom completion title, message, and optional follow-up link + +### Branching and flow logic +- Forward-only branching between later blocks +- Default next target when no branch rule matches +- Operator-based conditions by block type: + - equals / not equals + - is empty / is not empty + - contains + - contains any + - greater / greater-or-equal / less / less-or-equal +- Builder-side branching validation with publish blockers and advisory warnings +- Branch-aware public runner with visited-path navigation and recalculated progress +- Submission validation only for blocks actually visited in the chosen route + +### Responses +- Anonymous public submissions +- Response list and response detail views +- Branched response review with visited and skipped route context +- CSV and XLSX response export + +### Workspaces and collaboration +- Personal workspace +- Organization workspaces +- Organization owner administration +- Invite links for joining organizations +- Shared form management inside organizations + +### Creator experience +- Google sign-in for creators +- Dashboard grid and table views with sorting +- Profile settings for name, avatar, and locale +- Light / dark / system theme preference +- Localized UI in English and Russian ## Stack - Next.js App Router - TypeScript - Tailwind CSS -- shadcn/ui-style local primitives -- Framer Motion -- dnd-kit -- Auth.js (`next-auth`) with Google OAuth for creators +- Auth.js (`next-auth`) with Google OAuth - Prisma + PostgreSQL +- dnd-kit +- Framer Motion +- Bun for package management - Podman Compose for local Postgres -## Local setup - -### 1. Install dependencies +## Quick start ```bash bun install -``` - -### 2. Start Postgres with Podman - -```bash -bun run db:up -``` - -This uses `compose.yaml` and starts a local Postgres container on `localhost:5432`. - -### 3. Create local env file - -```bash cp .env.example .env -``` - -Fill in: -- `AUTH_SECRET` -- `AUTH_GOOGLE_ID` -- `AUTH_GOOGLE_SECRET` -- `NEXTAUTH_URL` (keep `http://localhost:3000` for local dev) - -Generate a secret, for example: - -```bash -openssl rand -base64 32 -``` - -### 4. Configure Google OAuth for local development - -Yes — Google OAuth can work locally, but you must create your own OAuth client in Google Cloud and allow localhost. - -In Google Cloud Console: - -1. Open **APIs & Services → Credentials** -2. Create an **OAuth 2.0 Client ID** -3. Choose **Web application** -4. Add these local settings: - -**Authorized JavaScript origins** -- `http://localhost:3000` - -**Authorized redirect URIs** -- `http://localhost:3000/api/auth/callback/google` - -Then copy the generated values into `.env`: - -```env -AUTH_GOOGLE_ID="your-client-id" -AUTH_GOOGLE_SECRET="your-client-secret" -``` - -If these values are missing or wrong, Google will show: -- `Error 401: invalid_client` -- `The OAuth client was not found` - -### 5. Run Prisma migration - -```bash +bun run db:up bun run prisma:migrate -``` - -### 6. Start the app - -```bash bun run dev ``` Open `http://localhost:3000`. +You must also configure Google OAuth for local development. See [docs/deployment.md](docs/deployment.md). + ## Useful commands ```bash @@ -99,40 +95,20 @@ bun run lint bun run db:up bun run db:down bun run db:logs +bun run db:reset bun run prisma:generate bun run prisma:migrate bun run prisma:studio ``` -## Product surfaces - -### Creator app -- `/dashboard` -- `/forms/[id]/edit` -- `/forms/[id]/responses` -- `/forms/[id]/responses/[responseId]` - -### Public app -- `/f/[slug]` +## Docs -## Current v0 scope - -- Creator Google sign-in -- Owned form dashboard -- Master-detail builder -- Block types: - - text - - short text - - long text - - single choice - - multiple choice -- Publish / unpublish -- Anonymous public submissions -- Responses list and detail views +- [Development](docs/development.md) +- [Deployment and environment setup](docs/deployment.md) ## Notes -- Creator auth is used only for creating, editing, publishing, and reviewing forms. -- Public respondents do not log in. +- Creator authentication is only required for building, publishing, and reviewing forms. +- Public respondents do not sign in. - Responses are stored anonymously. -- Editing a published form updates the live public form immediately in v0. +- Editing a published form updates the live form immediately. diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 0000000..0b2e358 --- /dev/null +++ b/docs/deployment.md @@ -0,0 +1,114 @@ +# Deployment and environment setup + +This project is a Next.js app backed by PostgreSQL and Auth.js with Google OAuth. + +## Required environment variables + +Copy `.env.example` to `.env` and provide values for: + +```env +DATABASE_URL="postgresql://..." +AUTH_SECRET="replace-with-a-long-random-string" +AUTH_GOOGLE_ID="your-google-client-id" +AUTH_GOOGLE_SECRET="your-google-client-secret" +NEXTAUTH_URL="http://localhost:3000" +``` + +Generate a strong auth secret, for example: + +```bash +openssl rand -base64 32 +``` + +## Local development setup + +### 1. Install dependencies + +```bash +bun install +``` + +### 2. Start PostgreSQL + +```bash +bun run db:up +``` + +This uses `compose.yaml` and starts Postgres on `localhost:5432`. + +### 3. Run Prisma migrations + +```bash +bun run prisma:migrate +``` + +### 4. Start the app + +```bash +bun run dev +``` + +## Google OAuth setup + +Create your own Google OAuth client in Google Cloud Console. + +### Local OAuth settings + +Use these values during local development: + +**Authorized JavaScript origins** +- `http://localhost:3000` + +**Authorized redirect URIs** +- `http://localhost:3000/api/auth/callback/google` + +If these values are missing or incorrect, Google sign-in will fail. + +### Production OAuth settings + +For a deployed environment, replace `localhost` with your real domain. + +Example: + +**Authorized JavaScript origins** +- `https://your-domain.example` + +**Authorized redirect URIs** +- `https://your-domain.example/api/auth/callback/google` + +Set `NEXTAUTH_URL` to the same public base URL. + +## Production deployment checklist + +1. Provision a PostgreSQL database. +2. Set the required environment variables. +3. Configure Google OAuth for the production domain. +4. Install dependencies: + + ```bash + bun install + ``` + +5. Run production database migrations: + + ```bash + bunx prisma migrate deploy + ``` + +6. Build the app: + + ```bash + bun run build + ``` + +7. Start the server with your process manager of choice: + + ```bash + bun run start + ``` + +## Notes + +- The build runs translation validation before Next.js production build. +- Response exports are generated inside the app; no separate worker is required. +- Editing a published form updates the live public form immediately. diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..4d1ed1b --- /dev/null +++ b/docs/development.md @@ -0,0 +1,121 @@ +# Development + +This document covers day-to-day local development for Lively Forms. + +## Prerequisites + +- Bun +- Podman + Podman Compose +- PostgreSQL container support via `compose.yaml` +- A Google OAuth client for creator sign-in during local development + +## Local setup + +```bash +bun install +cp .env.example .env +bun run db:up +bun run prisma:migrate +bun run dev +``` + +Open `http://localhost:3000`. + +For environment variables and OAuth setup details, see [deployment.md](./deployment.md). + +## Daily workflow + +### Start the database + +```bash +bun run db:up +``` + +### Start the app + +```bash +bun run dev +``` + +### Stop the database + +```bash +bun run db:down +``` + +### View database logs + +```bash +bun run db:logs +``` + +### Reset the local database volume + +```bash +bun run db:reset +``` + +## Database workflow + +Generate Prisma client after schema changes: + +```bash +bun run prisma:generate +``` + +Create and apply a local migration during development: + +```bash +bun run prisma:migrate +``` + +Open Prisma Studio: + +```bash +bun run prisma:studio +``` + +## Quality checks + +Run lint: + +```bash +bun run lint +``` + +Run a production build: + +```bash +bun run build +``` + +Notes: +- `bun run build` also validates translation resources before the Next.js build. +- There is currently no separate test suite command in `package.json`. + +## Important directories + +- `app/` — App Router pages, layouts, and API routes +- `components/` — UI and feature components +- `lib/` — business logic, auth, forms, branching, i18n, exports +- `locales/` — translation YAML files +- `prisma/` — schema and migrations +- `docs/` — project documentation +- `openspec/` — product/spec workflow artifacts + +## Important files + +- `lib/blocks.ts` — block types, config parsing, branch operator support +- `lib/branching.ts` — branching resolution and validation helpers +- `lib/forms.ts` — form loading, publish flow, submission shaping, response access +- `components/form-builder.tsx` — creator builder shell +- `components/form-builder-panels.tsx` — block settings and branching controls +- `components/public-form-runner.tsx` — public respondent flow + +## Notes for contributors + +- Use `bun` commands for project workflows. +- Creator routes require authentication; public form routes do not. +- Responses are stored anonymously. +- Editing a published form updates the live public form immediately. +- When changing UI copy, update both `locales/en.yml` and `locales/ru.yml`.