Skip to content

Commit b5875fc

Browse files
jon-belljon-bell
authored
Docs for polls and surveys
2 parents 88f0146 + 37290ae commit b5875fc

23 files changed

+2621
-1
lines changed

‎docs/developers/intro.md‎

Lines changed: 62 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,65 @@ sidebar_position: 1
66

77
This guide will help you understand and contribute to the Pawtograder project. Learn about the architecture, development setup, and how to extend the system.
88

9-
TODO
9+
## Getting Started
10+
11+
- **[Local Setup](./local-setup.md)** - Set up your development environment and run Pawtograder locally
12+
13+
## Feature Documentation
14+
15+
- **[Surveys](./surveys.md)** - Database schema, API, and implementation details for the survey system
16+
- **[Polls](./polls.md)** - Real-time polling system architecture, database schema, and hooks
17+
18+
## Tech Stack
19+
20+
Pawtograder is built with modern web technologies:
21+
22+
| Layer | Technology |
23+
|-------|------------|
24+
| Frontend | Next.js 15, React 18, TypeScript |
25+
| UI Framework | Chakra UI |
26+
| Backend | Supabase (PostgreSQL, Auth, Storage, Edge Functions) |
27+
| State Management | React Hook Form, Refine, TanStack Query |
28+
| Testing | Jest, Playwright |
29+
30+
## Repository Structure
31+
32+
```text
33+
platform/
34+
├── app/ # Next.js app router pages
35+
├── components/ # Reusable React components
36+
├── hooks/ # Custom React hooks
37+
├── types/ # TypeScript type definitions
38+
├── utils/ # Utility functions
39+
├── supabase/ # Database migrations and Edge Functions
40+
├── tests/ # Test files
41+
└── scripts/ # Build and utility scripts
42+
```
43+
44+
## Key Concepts
45+
46+
### Row-Level Security (RLS)
47+
48+
Pawtograder uses Supabase's Row Level Security to enforce access control at the database level. Each table has policies that determine what data users can read, create, update, or delete based on their role.
49+
50+
### User Roles
51+
52+
| Role | Description |
53+
|------|-------------|
54+
| `student` | Can view course content, submit assignments, respond to surveys |
55+
| `grader` | Student permissions plus grading access |
56+
| `instructor` | Full course management access |
57+
58+
### Profiles
59+
60+
Users have both public and private profiles per course:
61+
- **Public Profile**: Visible to other course members (name, avatar)
62+
- **Private Profile**: Internal identifier for submissions and responses
63+
64+
## Contributing
65+
66+
1. Fork the repository
67+
2. Create a feature branch
68+
3. Make your changes
69+
4. Run tests: `npm test` and `npx playwright test`
70+
5. Submit a pull request

‎docs/developers/local-setup.md‎

Lines changed: 315 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,315 @@
1+
---
2+
title: Local Setup
3+
sidebar_position: 2
4+
---
5+
6+
# Local Development Setup
7+
8+
This guide walks you through setting up Pawtograder for local development.
9+
10+
## Prerequisites
11+
12+
Before starting, ensure you have the following installed:
13+
14+
| Requirement | Version | Notes |
15+
|-------------|---------|-------|
16+
| Node.js | v22 (recommended) | Use [nvm](https://github.com/nvm-sh/nvm) for version management |
17+
| Docker | Latest | Required for local Supabase |
18+
| Git | Latest | For cloning the repository |
19+
20+
## Quick Start (Staging Backend)
21+
22+
The fastest way to get started is using our staging environment as a backend. This is ideal for frontend development that doesn't require database changes.
23+
24+
### Steps
25+
26+
1. **Clone the repository**
27+
```bash
28+
git clone https://github.com/pawtograder/platform.git
29+
cd platform
30+
```
31+
32+
2. **Install dependencies**
33+
```bash
34+
npm install
35+
```
36+
37+
3. **Configure environment**
38+
```bash
39+
cp .env.local.staging .env.local
40+
```
41+
42+
Edit `.env.local` and fill in your own values if needed.
43+
44+
4. **Start the development server**
45+
```bash
46+
npm run dev
47+
```
48+
49+
5. **Access the application**
50+
51+
Open `https://localhost:3000` in your browser. You'll need to accept the self-signed certificate warning (HTTPS is required for camera/microphone access in the help queue).
52+
53+
### Creating Test Accounts
54+
55+
In the staging environment, you can register with any email without confirmation:
56+
57+
- **Student account**: Use any email (e.g., `test@example.com`)
58+
- **Instructor account**: Include "instructor" in your email (e.g., `testinstructor@example.com`)
59+
60+
New accounts are automatically added to the demo class.
61+
62+
## Full Local Setup (Supabase)
63+
64+
For development requiring database changes, RLS policy modifications, or running E2E tests, you'll need a local Supabase instance.
65+
66+
### Prerequisites
67+
68+
- Docker installed and running
69+
- Node.js v22 or later
70+
71+
### Setup Steps
72+
73+
1. **Install dependencies**
74+
```bash
75+
npm install
76+
```
77+
78+
2. **Start Supabase**
79+
```bash
80+
npx supabase start
81+
```
82+
83+
This starts all Supabase services in Docker containers. First run may take several minutes to download images.
84+
85+
3. **Initialize the database**
86+
```bash
87+
npx supabase db reset
88+
```
89+
90+
This applies all migrations and seeds initial data.
91+
92+
4. **Configure environment variables**
93+
94+
After `supabase start`, you'll see output like:
95+
```
96+
API URL: http://127.0.0.1:54321
97+
anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
98+
service_role key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
99+
```
100+
101+
Update your `.env.local`:
102+
```bash
103+
SUPABASE_URL=http://127.0.0.1:54321
104+
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
105+
NEXT_PUBLIC_SUPABASE_ANON_KEY=<anon key from output>
106+
SUPABASE_SERVICE_ROLE_KEY=<service_role key from output>
107+
ENABLE_SIGNUPS=true
108+
```
109+
110+
:::warning
111+
Never expose `SUPABASE_SERVICE_ROLE_KEY` to the browser or commit it to version control. Keep it in server-only code and CI secrets.
112+
:::
113+
114+
5. **Build the application**
115+
```bash
116+
npm run build
117+
```
118+
119+
6. **Start Edge Functions**
120+
```bash
121+
npx supabase functions serve
122+
```
123+
124+
7. **Start the development server**
125+
```bash
126+
npm start
127+
```
128+
129+
8. **Seed test data (optional)**
130+
```bash
131+
npm run seed
132+
```
133+
134+
This creates a test class with students and assignments. Scroll up in the output to find "Login Credentials" with email/password pairs.
135+
136+
## Local Services
137+
138+
Once Supabase is running, these services are available:
139+
140+
| Service | URL | Description |
141+
|---------|-----|-------------|
142+
| API | http://127.0.0.1:54321 | Supabase REST API |
143+
| Studio | http://localhost:54323 | Database management UI |
144+
| Inbucket | http://localhost:54324 | Email testing interface |
145+
| Application | https://localhost:3000 | Next.js frontend |
146+
147+
### Supabase Studio
148+
149+
Access the Supabase dashboard at `http://localhost:54323` to:
150+
151+
- Browse and edit database tables
152+
- View and manage auth users
153+
- Test RLS policies
154+
- Monitor realtime subscriptions
155+
- Manage storage buckets
156+
157+
### Email Testing
158+
159+
View captured emails at `http://localhost:54324`. Useful for testing:
160+
161+
- Authentication flows (magic links, password reset)
162+
- Notification emails
163+
- Email verification
164+
165+
## Development Commands
166+
167+
### Daily Development
168+
169+
```bash
170+
# Start dev server with hot reload
171+
npm run dev
172+
173+
# Run linting
174+
npm run lint
175+
176+
# Format code
177+
npm run format
178+
179+
# Run type checking
180+
npm run typecheck:functions
181+
```
182+
183+
### Database Operations
184+
185+
```bash
186+
# Start Supabase services
187+
npx supabase start
188+
189+
# Stop Supabase services
190+
npx supabase stop
191+
192+
# Reset database (reapply migrations + seed)
193+
npx supabase db reset
194+
195+
# Create a new migration
196+
npx supabase migration new migration_name
197+
198+
# Generate TypeScript types from schema
199+
npm run client-local
200+
```
201+
202+
### Testing
203+
204+
```bash
205+
# Run unit tests
206+
npm test
207+
208+
# Run unit tests in watch mode
209+
npm run test:watch
210+
211+
# Run E2E tests with UI
212+
npx playwright test --ui
213+
214+
# Run specific E2E test file
215+
npx playwright test surveys
216+
```
217+
218+
### Seeding Data
219+
220+
```bash
221+
# Create test class with sample data
222+
npm run seed
223+
```
224+
225+
## Project Structure
226+
227+
```
228+
platform/
229+
├── app/ # Next.js app router pages
230+
│ └── course/[course_id]/ # Course-specific routes
231+
├── components/ # Reusable React components
232+
├── hooks/ # Custom React hooks
233+
├── types/ # TypeScript type definitions
234+
├── utils/ # Utility functions
235+
│ └── supabase/ # Supabase client configuration
236+
├── supabase/
237+
│ ├── migrations/ # Database migrations
238+
│ ├── functions/ # Edge Functions (Deno)
239+
│ ├── seed.sql # Initial seed data
240+
│ └── config.toml # Supabase configuration
241+
├── tests/
242+
│ └── e2e/ # Playwright E2E tests
243+
├── public/ # Static assets
244+
└── scripts/ # Build and utility scripts
245+
```
246+
247+
## Environment Variables
248+
249+
### Required Variables
250+
251+
| Variable | Description |
252+
|----------|-------------|
253+
| `NEXT_PUBLIC_SUPABASE_URL` | Supabase API URL |
254+
| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Supabase anonymous key |
255+
| `SUPABASE_URL` | Supabase API URL (server-side) |
256+
| `SUPABASE_SERVICE_ROLE_KEY` | Supabase service role key (server-side only) |
257+
258+
### Optional Variables
259+
260+
| Variable | Description |
261+
|----------|-------------|
262+
| `ENABLE_SIGNUPS` | Enable user registration UI (`true`/`false`) |
263+
| `END_TO_END_SECRET` | Secret for E2E test authentication |
264+
265+
## Troubleshooting
266+
267+
### Supabase won't start
268+
269+
1. Ensure Docker is running
270+
2. Check for port conflicts (54321, 54323, 54324)
271+
3. Try stopping and removing containers:
272+
```bash
273+
npx supabase stop --no-backup
274+
docker system prune
275+
npx supabase start
276+
```
277+
278+
### Database connection errors
279+
280+
1. Verify Supabase is running: `npx supabase status`
281+
2. Check `.env.local` has correct URLs and keys
282+
3. Ensure you ran `npx supabase db reset` after starting
283+
284+
### TypeScript errors after schema changes
285+
286+
Regenerate types after any database changes:
287+
```bash
288+
npm run client-local
289+
```
290+
291+
### HTTPS certificate warnings
292+
293+
The dev server uses a self-signed certificate. This is expected:
294+
- Click "Advanced" → "Proceed to localhost"
295+
- Or add an exception in your browser settings
296+
297+
### Edge Functions not working
298+
299+
1. Ensure functions are running: `npx supabase functions serve`
300+
2. Check the terminal for function errors
301+
3. Verify function URLs in your requests
302+
303+
### Hot reload not working
304+
305+
1. Check for file system watcher limits (Linux):
306+
```bash
307+
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
308+
sudo sysctl -p
309+
```
310+
2. Restart the dev server
311+
312+
## Next Steps
313+
314+
- Read the [Surveys Developer Guide](./surveys.md) for feature-specific documentation
315+
- Join the development discussion on GitHub Issues

0 commit comments

Comments
 (0)