📑 Formly – A Modern Full-Stack Form Management Platform

A production-inspired full-stack web application demonstrating modern software engineering practices through a scalable client-server architecture, responsive user interface, RESTful APIs, and cloud deployment.

---

📚 Table of Contents

• Live Demo
• Features
• Tech Stack
• Architecture Overview
• Folder Structure
• Database Schema
• API Documentation
• Screenshots
• Installation & Setup
• Environment Variables
• Deployment Guide
• Assumptions
• Future Improvements
• Acknowledgements

---

🌐 Live Demo

• Frontend (Vercel): https://formly-typeform-clone.vercel.app
• Backend (Render): https://formly-typeform-clone.onrender.com
• API Documentation (Swagger): https://formly-typeform-clone.onrender.com/docs
• GitHub Repository: https://github.com/agrawalanshika/Formly-Typeform-clone

---

✨ Features

Category	Highlights
📋 Dashboard	Create, duplicate, delete, and manage forms • Search and sort forms • Responsive dashboard interface
🛠️ Form Builder	Drag-and-drop question reordering • Multiple question types • Required field support • Question descriptions • Live preview • Publish/Unpublish forms
👤 Respondent Experience	One-question-at-a-time interface • Progress indicator • Input validation • Shareable public links
📊 Responses & Analytics	View submitted responses • Per-question statistics • Rating summaries • Choice distributions
⚙️ Backend	RESTful FastAPI API • SQLAlchemy ORM • SQLite persistence • Automatic seed data

🛠️ Tech Stack

Frontend: Next.js 15 (App Router) · TypeScript · TailwindCSS · Framer Motion · React Hook Form + Zod · Axios · dnd-kit

Backend: Python · FastAPI · SQLAlchemy · Pydantic · SQLite

Deployment: Frontend → Vercel · Backend → Render · Database → SQLite

---

⬇️ Architecture Overview

The app is a classic client/server split:

• The Next.js frontend is a pure client of the API — it never talks to the database directly. Every page fetches through services/*.ts (thin Axios wrappers) into typed TypeScript interfaces in types/*.ts.
• The FastAPI backend exposes a REST API. Each router handles HTTP concerns only; anything resembling business logic (duplicating a form, computing statistics) lives in app/services/, keeping routers thin and readable.
• The respondent flow requires no authentication — publishing a form generates a random share_slug used as its public URL. A separate /api/public/forms/{share_slug} endpoint only returns forms that are actually published, so drafts are never exposed.
• Creator authentication is intentionally out of scope for this assignment (per the spec) — the app assumes a single default creator.

Browser ── Next.js (Vercel) ── Axios/HTTP ── FastAPI (Render) ── SQLAlchemy ── SQLite

---

📂 Folder Structure

typeform-clone/
├── frontend/
│   ├── app/                  # Next.js App Router pages
│   │   ├── dashboard/
│   │   ├── builder/[formId]/
│   │   ├── form/[formId]/        # public respondent flow (formId = share_slug)
│   │   └── responses/[formId]/
│   ├── components/
│   │   ├── ui/                # Button, Input, Badge, Modal, Toggle
│   │   ├── builder/            # question editor, sidebar, live preview
│   │   ├── dashboard/          # form cards, create/delete modals
│   │   ├── public-form/        # question screen, progress bar, thank-you
│   │   └── responses/          # stat cards, response table/detail
│   ├── hooks/                  # useForm, useKeyboardNav
│   ├── services/                # api.ts + typed calls per resource
│   ├── lib/                     # utils.ts (cn), validation.ts (Zod)
│   ├── types/                   # shared TS interfaces mirroring backend schemas
│   └── styles/                  # Tailwind globals + theme tokens
│
├── backend/
│   ├── app/
│   │   ├── routers/    # forms.py, questions.py, responses.py, stats.py
│   │   ├── models/     # SQLAlchemy: Form, Question, QuestionOption, Response, Answer
│   │   ├── schemas/    # Pydantic request/response shapes
│   │   ├── services/   # form_service.py, stats_service.py
│   │   ├── database/   # engine/session setup
│   │   └── main.py     # app instance, CORS, router registration
│   ├── seed.py          # seeds 2 published forms + ~21 responses
│   └── requirements.txt
│
└── README.md

---

📊 Database Schema

Forms
├── id            INTEGER PK
├── title         TEXT NOT NULL
├── description   TEXT NULL
├── status        TEXT NOT NULL      -- "draft" | "published"
├── share_slug    TEXT UNIQUE        -- public URL id, set on publish
├── created_at    DATETIME
└── updated_at    DATETIME

Questions
├── id            INTEGER PK
├── form_id       INTEGER FK -> Forms.id (CASCADE DELETE)
├── type          TEXT NOT NULL      -- short_text|long_text|multiple_choice|
│                                       dropdown|email|number|yes_no|rating
├── title         TEXT NOT NULL
├── description   TEXT NULL          -- help text
├── placeholder   TEXT NULL
├── is_required   BOOLEAN DEFAULT FALSE
├── order_index   INTEGER NOT NULL   -- drives drag-and-drop order
└── rating_max    INTEGER NULL       -- only for type = rating

QuestionOptions                       -- for multiple_choice / dropdown
├── id            INTEGER PK
├── question_id   INTEGER FK -> Questions.id (CASCADE DELETE)
├── label         TEXT NOT NULL
└── order_index   INTEGER NOT NULL

Responses                             -- one row per submission
├── id            INTEGER PK
├── form_id       INTEGER FK -> Forms.id (CASCADE DELETE)
├── submitted_at  DATETIME
└── is_complete   BOOLEAN DEFAULT TRUE

Answers                               -- one row per question per response
├── id            INTEGER PK
├── response_id   INTEGER FK -> Responses.id (CASCADE DELETE)
├── question_id   INTEGER FK -> Questions.id
└── value         TEXT NOT NULL       -- stored as text for every question type

🧷 ER Diagram

Forms 1 ──── * Questions 1 ──── * QuestionOptions
  │
  └──── * Responses 1 ──── * Answers ──── * Questions

Design notes

• Answers.value is TEXT for every question type (numbers and choices included) instead of a nullable column per type. This keeps one simple, normalized table instead of column sprawl, and is trivial to parse back into the right type in the stats layer (stats_service.py).
• Cascade deletes are used throughout (ondelete="CASCADE" + SQLAlchemy cascade="all, delete-orphan"), so deleting a form cleanly removes its questions, options, responses, and answers.
• order_index on both Questions and QuestionOptions is what powers drag-and-drop reordering in the builder; it's re-numbered contiguously whenever a question is deleted.

---

📃 API Documentation

All endpoints are prefixed as shown. FastAPI also serves interactive docs at /docs (Swagger UI) once the backend is running.

Forms

Method	Path	Description
GET	/api/forms	List all forms (id, title, status, response_count)
POST	/api/forms	Create a form
GET	/api/forms/{id}	Get a form with its ordered questions
PATCH	/api/forms/{id}	Rename / update description
DELETE	/api/forms/{id}	Delete a form (cascades)
POST	/api/forms/{id}/duplicate	Duplicate a form + its questions
POST	/api/forms/{id}/publish	Publish, generating a share_slug
POST	/api/forms/{id}/unpublish	Revert to draft
GET	/api/public/forms/{share_slug}	Public, no auth — used by the respondent flow

Questions

Method	Path	Description
POST	/api/forms/{formId}/questions	Create a question
PATCH	/api/questions/{id}	Update a question
DELETE	/api/questions/{id}	Delete a question
POST	/api/forms/{formId}/questions/reorder	Bulk-update order_index

Responses

Method	Path	Description
POST	/api/forms/{formId}/responses	Public — submit a filled-out form
GET	/api/forms/{formId}/responses	List all responses for a form
GET	/api/responses/{id}	Get one response with all its answers

Stats

Method	Path	Description
GET	/api/forms/{formId}/stats	Per-question choice counts / averages

---

📸 Screenshots

Dashboard	Form Builder

Responses Dashboard	Respondent Page

---

⚙️ Installation & Setup

Backend

cd backend
python -m venv venv && source venv/bin/activate   # optional but recommended
pip install -r requirements.txt
cp .env.example .env                                # adjust if needed
python seed.py                                       # seeds 2 forms + 21 responses
uvicorn app.main:app --reload                         # runs on http://localhost:8000

Frontend

cd frontend
npm install
cp .env.example .env.local                # NEXT_PUBLIC_API_URL=http://localhost:8000
npm run dev                                 # runs on http://localhost:3000

Then open http://localhost:3000 — it redirects to /dashboard, which already has two seeded forms ("Job Application" and "Customer Feedback") ready to explore.

---

Environment Variables

backend/.env

Variable	Description	Default
ALLOWED_ORIGINS	Comma-separated frontend origins allowed by CORS	*

frontend/.env.local

Variable	Description	Default
NEXT_PUBLIC_API_URL	URL of the FastAPI backend	http://localhost:8000

Production: Set NEXT_PUBLIC_API_URL=https://formly-typeform-clone.onrender.com when deploying to Vercel.

---

🎯 Deployment Guide

Backend → Render

1. Push this repo to GitHub.
2. On render.com, create a New Web Service pointing at the backend/ directory (or use the included render.yaml).
3. Build command: pip install -r requirements.txt
4. Start command: python seed.py && uvicorn app.main:app --host 0.0.0.0 --port $PORT
5. Set the ALLOWED_ORIGINS environment variable to your Vercel URL once you have it (e.g. https://your-app.vercel.app).
6. Note: Render's free-tier filesystem is ephemeral — the SQLite database resets on every redeploy/restart. This is an accepted, documented tradeoff for a 24-hour assignment; seed.py re-seeds automatically on each boot (it's a no-op if data already exists).

Frontend → Vercel

1. Import the repo into vercel.com, set the root directory to frontend/.
2. Set the environment variable NEXT_PUBLIC_API_URL to your deployed Render backend URL.
3. Deploy — Vercel auto-detects the Next.js app.

---

Assumptions

• Creator authentication is simplified per the assignment spec — the app assumes a single default creator with no login.
• File-upload, payments, integrations, and team collaboration are shown as "Coming soon" placeholders where relevant, as explicitly permitted by the assignment.
• SQLite is used per the required tech stack; see the Render note above regarding persistence on free-tier hosting.

---

⚠️ Note

The backend is hosted on Render's free tier.

If the API has been inactive for some time, the first request may take 30–60 seconds while the server wakes up.

---

🔮 Future Improvements

Bonus features, in priority order (not yet implemented):

1. Export responses as CSV
2. Partial response tracking / completion rate (the is_complete column on Responses already anticipates this)
3. Conditional logic / branching between questions
4. File upload question type
5. Custom themes (colors, fonts, backgrounds)

---

📌 Acknowledgements

This project was developed as part of the Scalar AI Labs SDE Internship Assignment and has been further refined for portfolio and learning purposes.

---

👧🏻 Author

Anshika Agrawal