this repo has no description
docs: refresh readme and add development guide
+309
-98
+74
-98
README.md
+74
-98
README.md
···
1
1
# Lively Forms
2
2
3
-
Lively Forms is a Typeform-inspired conversational form builder built with Next.js, Auth.js, Prisma, PostgreSQL, Tailwind, Framer Motion, and dnd-kit.
3
+
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.
4
+
5
+
## Features
6
+
7
+
### Form building
8
+
- Master-detail form builder with block reordering
9
+
- Supported block types:
10
+
- text
11
+
- short text
12
+
- long text
13
+
- single choice
14
+
- multiple choice
15
+
- number
16
+
- link
17
+
- agreement
18
+
- date
19
+
- Required questions
20
+
- Type-specific validation:
21
+
- text regex validation
22
+
- number min/max and integer-only rules
23
+
- link validation
24
+
- date validation
25
+
- agreement validation
26
+
- Publish / unpublish controls
27
+
- Shareable public form slugs
28
+
- Custom completion title, message, and optional follow-up link
29
+
30
+
### Branching and flow logic
31
+
- Forward-only branching between later blocks
32
+
- Default next target when no branch rule matches
33
+
- Operator-based conditions by block type:
34
+
- equals / not equals
35
+
- is empty / is not empty
36
+
- contains
37
+
- contains any
38
+
- greater / greater-or-equal / less / less-or-equal
39
+
- Builder-side branching validation with publish blockers and advisory warnings
40
+
- Branch-aware public runner with visited-path navigation and recalculated progress
41
+
- Submission validation only for blocks actually visited in the chosen route
42
+
43
+
### Responses
44
+
- Anonymous public submissions
45
+
- Response list and response detail views
46
+
- Branched response review with visited and skipped route context
47
+
- CSV and XLSX response export
48
+
49
+
### Workspaces and collaboration
50
+
- Personal workspace
51
+
- Organization workspaces
52
+
- Organization owner administration
53
+
- Invite links for joining organizations
54
+
- Shared form management inside organizations
55
+
56
+
### Creator experience
57
+
- Google sign-in for creators
58
+
- Dashboard grid and table views with sorting
59
+
- Profile settings for name, avatar, and locale
60
+
- Light / dark / system theme preference
61
+
- Localized UI in English and Russian
4
62
5
63
## Stack
6
64
7
65
- Next.js App Router
8
66
- TypeScript
9
67
- Tailwind CSS
10
-
- shadcn/ui-style local primitives
68
+
- Auth.js (`next-auth`) with Google OAuth
69
+
- Prisma + PostgreSQL
70
+
- dnd-kit
11
71
- Framer Motion
12
-
- dnd-kit
13
-
- Auth.js (`next-auth`) with Google OAuth for creators
14
-
- Prisma + PostgreSQL
72
+
- Bun for package management
15
73
- Podman Compose for local Postgres
16
74
17
-
## Local setup
18
-
19
-
### 1. Install dependencies
75
+
## Quick start
20
76
21
77
```bash
22
78
bun install
23
-
```
24
-
25
-
### 2. Start Postgres with Podman
26
-
27
-
```bash
28
-
bun run db:up
29
-
```
30
-
31
-
This uses `compose.yaml` and starts a local Postgres container on `localhost:5432`.
32
-
33
-
### 3. Create local env file
34
-
35
-
```bash
36
79
cp .env.example .env
37
-
```
38
-
39
-
Fill in:
40
-
- `AUTH_SECRET`
41
-
- `AUTH_GOOGLE_ID`
42
-
- `AUTH_GOOGLE_SECRET`
43
-
- `NEXTAUTH_URL` (keep `http://localhost:3000` for local dev)
44
-
45
-
Generate a secret, for example:
46
-
47
-
```bash
48
-
openssl rand -base64 32
49
-
```
50
-
51
-
### 4. Configure Google OAuth for local development
52
-
53
-
Yes — Google OAuth can work locally, but you must create your own OAuth client in Google Cloud and allow localhost.
54
-
55
-
In Google Cloud Console:
56
-
57
-
1. Open **APIs & Services → Credentials**
58
-
2. Create an **OAuth 2.0 Client ID**
59
-
3. Choose **Web application**
60
-
4. Add these local settings:
61
-
62
-
**Authorized JavaScript origins**
63
-
- `http://localhost:3000`
64
-
65
-
**Authorized redirect URIs**
66
-
- `http://localhost:3000/api/auth/callback/google`
67
-
68
-
Then copy the generated values into `.env`:
69
-
70
-
```env
71
-
AUTH_GOOGLE_ID="your-client-id"
72
-
AUTH_GOOGLE_SECRET="your-client-secret"
73
-
```
74
-
75
-
If these values are missing or wrong, Google will show:
76
-
- `Error 401: invalid_client`
77
-
- `The OAuth client was not found`
78
-
79
-
### 5. Run Prisma migration
80
-
81
-
```bash
80
+
bun run db:up
82
81
bun run prisma:migrate
83
-
```
84
-
85
-
### 6. Start the app
86
-
87
-
```bash
88
82
bun run dev
89
83
```
90
84
91
85
Open `http://localhost:3000`.
86
+
87
+
You must also configure Google OAuth for local development. See [docs/deployment.md](docs/deployment.md).
92
88
93
89
## Useful commands
94
90
···
99
95
bun run db:up
100
96
bun run db:down
101
97
bun run db:logs
98
+
bun run db:reset
102
99
bun run prisma:generate
103
100
bun run prisma:migrate
104
101
bun run prisma:studio
105
102
```
106
103
107
-
## Product surfaces
104
+
## Docs
108
105
109
-
### Creator app
110
-
- `/dashboard`
111
-
- `/forms/[id]/edit`
112
-
- `/forms/[id]/responses`
113
-
- `/forms/[id]/responses/[responseId]`
114
-
115
-
### Public app
116
-
- `/f/[slug]`
117
-
118
-
## Current v0 scope
119
-
120
-
- Creator Google sign-in
121
-
- Owned form dashboard
122
-
- Master-detail builder
123
-
- Block types:
124
-
- text
125
-
- short text
126
-
- long text
127
-
- single choice
128
-
- multiple choice
129
-
- Publish / unpublish
130
-
- Anonymous public submissions
131
-
- Responses list and detail views
106
+
- [Development](docs/development.md)
107
+
- [Deployment and environment setup](docs/deployment.md)
132
108
133
109
## Notes
134
110
135
-
- Creator auth is used only for creating, editing, publishing, and reviewing forms.
136
-
- Public respondents do not log in.
111
+
- Creator authentication is only required for building, publishing, and reviewing forms.
112
+
- Public respondents do not sign in.
137
113
- Responses are stored anonymously.
138
-
- Editing a published form updates the live public form immediately in v0.
114
+
- Editing a published form updates the live form immediately.
+114
docs/deployment.md
+114
docs/deployment.md
···
1
+
# Deployment and environment setup
2
+
3
+
This project is a Next.js app backed by PostgreSQL and Auth.js with Google OAuth.
4
+
5
+
## Required environment variables
6
+
7
+
Copy `.env.example` to `.env` and provide values for:
8
+
9
+
```env
10
+
DATABASE_URL="postgresql://..."
11
+
AUTH_SECRET="replace-with-a-long-random-string"
12
+
AUTH_GOOGLE_ID="your-google-client-id"
13
+
AUTH_GOOGLE_SECRET="your-google-client-secret"
14
+
NEXTAUTH_URL="http://localhost:3000"
15
+
```
16
+
17
+
Generate a strong auth secret, for example:
18
+
19
+
```bash
20
+
openssl rand -base64 32
21
+
```
22
+
23
+
## Local development setup
24
+
25
+
### 1. Install dependencies
26
+
27
+
```bash
28
+
bun install
29
+
```
30
+
31
+
### 2. Start PostgreSQL
32
+
33
+
```bash
34
+
bun run db:up
35
+
```
36
+
37
+
This uses `compose.yaml` and starts Postgres on `localhost:5432`.
38
+
39
+
### 3. Run Prisma migrations
40
+
41
+
```bash
42
+
bun run prisma:migrate
43
+
```
44
+
45
+
### 4. Start the app
46
+
47
+
```bash
48
+
bun run dev
49
+
```
50
+
51
+
## Google OAuth setup
52
+
53
+
Create your own Google OAuth client in Google Cloud Console.
54
+
55
+
### Local OAuth settings
56
+
57
+
Use these values during local development:
58
+
59
+
**Authorized JavaScript origins**
60
+
- `http://localhost:3000`
61
+
62
+
**Authorized redirect URIs**
63
+
- `http://localhost:3000/api/auth/callback/google`
64
+
65
+
If these values are missing or incorrect, Google sign-in will fail.
66
+
67
+
### Production OAuth settings
68
+
69
+
For a deployed environment, replace `localhost` with your real domain.
70
+
71
+
Example:
72
+
73
+
**Authorized JavaScript origins**
74
+
- `https://your-domain.example`
75
+
76
+
**Authorized redirect URIs**
77
+
- `https://your-domain.example/api/auth/callback/google`
78
+
79
+
Set `NEXTAUTH_URL` to the same public base URL.
80
+
81
+
## Production deployment checklist
82
+
83
+
1. Provision a PostgreSQL database.
84
+
2. Set the required environment variables.
85
+
3. Configure Google OAuth for the production domain.
86
+
4. Install dependencies:
87
+
88
+
```bash
89
+
bun install
90
+
```
91
+
92
+
5. Run production database migrations:
93
+
94
+
```bash
95
+
bunx prisma migrate deploy
96
+
```
97
+
98
+
6. Build the app:
99
+
100
+
```bash
101
+
bun run build
102
+
```
103
+
104
+
7. Start the server with your process manager of choice:
105
+
106
+
```bash
107
+
bun run start
108
+
```
109
+
110
+
## Notes
111
+
112
+
- The build runs translation validation before Next.js production build.
113
+
- Response exports are generated inside the app; no separate worker is required.
114
+
- Editing a published form updates the live public form immediately.
+121
docs/development.md
+121
docs/development.md
···
1
+
# Development
2
+
3
+
This document covers day-to-day local development for Lively Forms.
4
+
5
+
## Prerequisites
6
+
7
+
- Bun
8
+
- Podman + Podman Compose
9
+
- PostgreSQL container support via `compose.yaml`
10
+
- A Google OAuth client for creator sign-in during local development
11
+
12
+
## Local setup
13
+
14
+
```bash
15
+
bun install
16
+
cp .env.example .env
17
+
bun run db:up
18
+
bun run prisma:migrate
19
+
bun run dev
20
+
```
21
+
22
+
Open `http://localhost:3000`.
23
+
24
+
For environment variables and OAuth setup details, see [deployment.md](./deployment.md).
25
+
26
+
## Daily workflow
27
+
28
+
### Start the database
29
+
30
+
```bash
31
+
bun run db:up
32
+
```
33
+
34
+
### Start the app
35
+
36
+
```bash
37
+
bun run dev
38
+
```
39
+
40
+
### Stop the database
41
+
42
+
```bash
43
+
bun run db:down
44
+
```
45
+
46
+
### View database logs
47
+
48
+
```bash
49
+
bun run db:logs
50
+
```
51
+
52
+
### Reset the local database volume
53
+
54
+
```bash
55
+
bun run db:reset
56
+
```
57
+
58
+
## Database workflow
59
+
60
+
Generate Prisma client after schema changes:
61
+
62
+
```bash
63
+
bun run prisma:generate
64
+
```
65
+
66
+
Create and apply a local migration during development:
67
+
68
+
```bash
69
+
bun run prisma:migrate
70
+
```
71
+
72
+
Open Prisma Studio:
73
+
74
+
```bash
75
+
bun run prisma:studio
76
+
```
77
+
78
+
## Quality checks
79
+
80
+
Run lint:
81
+
82
+
```bash
83
+
bun run lint
84
+
```
85
+
86
+
Run a production build:
87
+
88
+
```bash
89
+
bun run build
90
+
```
91
+
92
+
Notes:
93
+
- `bun run build` also validates translation resources before the Next.js build.
94
+
- There is currently no separate test suite command in `package.json`.
95
+
96
+
## Important directories
97
+
98
+
- `app/` — App Router pages, layouts, and API routes
99
+
- `components/` — UI and feature components
100
+
- `lib/` — business logic, auth, forms, branching, i18n, exports
101
+
- `locales/` — translation YAML files
102
+
- `prisma/` — schema and migrations
103
+
- `docs/` — project documentation
104
+
- `openspec/` — product/spec workflow artifacts
105
+
106
+
## Important files
107
+
108
+
- `lib/blocks.ts` — block types, config parsing, branch operator support
109
+
- `lib/branching.ts` — branching resolution and validation helpers
110
+
- `lib/forms.ts` — form loading, publish flow, submission shaping, response access
111
+
- `components/form-builder.tsx` — creator builder shell
112
+
- `components/form-builder-panels.tsx` — block settings and branching controls
113
+
- `components/public-form-runner.tsx` — public respondent flow
114
+
115
+
## Notes for contributors
116
+
117
+
- Use `bun` commands for project workflows.
118
+
- Creator routes require authentication; public form routes do not.
119
+
- Responses are stored anonymously.
120
+
- Editing a published form updates the live public form immediately.
121
+
- When changing UI copy, update both `locales/en.yml` and `locales/ru.yml`.