Skip to content

Commit 498e9e9

Browse files
prithaxdevprithaxdev
committed
docs: simplify development guide
1 parent a3be80a commit 498e9e9

1 file changed

Lines changed: 23 additions & 257 deletions

File tree

‎DEVELOPMENT.md‎

Lines changed: 23 additions & 257 deletions
Original file line numberDiff line numberDiff line change
@@ -1,293 +1,59 @@
1-
# CodePulse — Development Guide
1+
# Running CodePulse Locally
22

3-
Developer learning retention platform using spaced repetition (SM-2), TF-IDF search, K-means clustering, and Levenshtein duplicate detection.
4-
5-
---
6-
7-
## Stack
8-
9-
| Layer | Technology |
10-
|-------|-----------|
11-
| Frontend | Next.js 16, TypeScript, Tailwind CSS v4, Shadcn/UI |
12-
| Auth | Clerk (Google OAuth) |
13-
| Database | Supabase (PostgreSQL) |
14-
| Algorithm API | FastAPI (Python 3.12) |
15-
| Package manager | pnpm (workspace monorepo) |
16-
| Deployment | Vercel (frontend) · Railway (API) |
17-
18-
---
19-
20-
## Prerequisites
21-
22-
- Node.js 20+
23-
- Python 3.12+
24-
- pnpm — `npm install -g pnpm`
25-
- Supabase CLI — `brew install supabase/tap/supabase`
26-
27-
---
28-
29-
## Running Locally
30-
31-
### 1. Clone and install
3+
## 1. Install dependencies
324

335
```bash
34-
git clone git@github.com:prithaxdev/CodePulse.git
35-
cd CodePulse
366
pnpm install
377
```
388

39-
### 2. Set up environment variables
40-
41-
Create `apps/web/.env.local`:
42-
43-
```bash
44-
# Supabase — get from supabase.com → your project → Settings → API
45-
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
46-
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
47-
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
48-
49-
# Clerk — get from clerk.com → your app → API Keys
50-
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
51-
CLERK_SECRET_KEY=sk_test_...
52-
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
53-
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
54-
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/dashboard
55-
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/onboarding
56-
57-
# FastAPI — local dev URL
58-
NEXT_PUBLIC_API_URL=http://localhost:8000
59-
```
60-
61-
Create `apps/api/.env`:
62-
63-
```bash
64-
# Supabase (same values as above)
65-
SUPABASE_URL=https://your-project.supabase.co
66-
SUPABASE_KEY=your_service_role_key
67-
68-
# CORS — allow local Next.js dev server
69-
CORS_ORIGINS=http://localhost:3000
70-
```
71-
72-
### 3. Set up the database
73-
74-
Link Supabase CLI to your project:
75-
76-
```bash
77-
supabase login
78-
supabase link --project-ref your-project-ref
79-
```
80-
81-
Run the schema (creates users, snippets, review_logs tables):
82-
83-
```bash
84-
supabase db query "$(cat supabase/schema.sql)" --linked
85-
```
86-
87-
> If `supabase/schema.sql` doesn't exist yet, copy the SQL from the Database Schema section below and paste it into the Supabase SQL editor at supabase.com.
88-
89-
### 4. Start the FastAPI backend
90-
91-
```bash
92-
cd apps/api
93-
python -m venv .venv
94-
source .venv/bin/activate # Windows: .venv\Scripts\activate
95-
pip install -e ".[dev]"
96-
uvicorn app.main:app --reload --port 8000
97-
```
98-
99-
API docs available at: **http://localhost:8000/docs**
100-
101-
### 5. Start the Next.js frontend
102-
103-
In a new terminal:
9+
## 2. Start the frontend
10410

10511
```bash
10612
cd apps/web
10713
pnpm dev
10814
```
10915

110-
App runs at: **http://localhost:3000**
16+
Opens at **http://localhost:3000**
11117

112-
---
113-
114-
## Clerk Webhook (local dev)
115-
116-
The Clerk webhook syncs new users to Supabase. For local testing, use the Clerk CLI to tunnel events to localhost:
18+
## 3. Start the backend (algorithm API)
11719

11820
```bash
119-
npx @clerk/cli@latest webhooks listen \
120-
--webhook-secret whsec_your_secret \
121-
http://localhost:3000/api/webhooks/clerk
122-
```
123-
124-
---
125-
126-
## Project Structure
127-
128-
```
129-
CodePulse/
130-
├── apps/
131-
│ ├── web/ # Next.js frontend
132-
│ │ ├── app/
133-
│ │ │ ├── (app)/ # Authenticated routes (dashboard, review, search…)
134-
│ │ │ ├── (auth)/ # Sign-in / sign-up pages
135-
│ │ │ └── api/webhooks/ # Clerk webhook endpoint
136-
│ │ ├── components/ # UI components (sidebar, due-badge…)
137-
│ │ ├── hooks/ # TanStack Query hooks
138-
│ │ ├── lib/ # Supabase clients, API client
139-
│ │ └── types/ # TypeScript types
140-
│ │
141-
│ └── api/ # FastAPI algorithm engine
142-
│ ├── app/
143-
│ │ ├── algorithms/ # SM-2, TF-IDF, K-means, Levenshtein, summarizer
144-
│ │ ├── routes/ # FastAPI route handlers
145-
│ │ └── models/ # Pydantic schemas
146-
│ └── tests/ # pytest test suite
147-
│
148-
├── package.json # Workspace root
149-
└── pnpm-workspace.yaml # pnpm monorepo config
21+
cd apps/api
22+
source .venv/bin/activate
23+
uvicorn app.main:app --reload --port 8000
15024
```
15125

152-
---
153-
154-
## Available Commands
155-
156-
### Frontend
157-
158-
```bash
159-
pnpm --filter web dev # Start dev server
160-
pnpm --filter web build # Production build
161-
pnpm --filter web typecheck # TypeScript check
162-
pnpm --filter web lint # ESLint
163-
```
26+
API docs at **http://localhost:8000/docs**
16427

165-
### Backend
28+
## 4. Run backend tests
16629

16730
```bash
16831
cd apps/api
169-
pytest -v # Run all tests
170-
pytest tests/test_sm2.py -v # Run specific test file
171-
uvicorn app.main:app --reload # Start dev server
172-
```
173-
174-
### Database
175-
176-
```bash
177-
supabase db query "SELECT * FROM users;" --linked # Run SQL
178-
supabase db pull --linked # Pull remote schema
179-
```
180-
181-
---
182-
183-
## Database Schema
184-
185-
```sql
186-
CREATE TABLE users (
187-
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
188-
clerk_id TEXT UNIQUE NOT NULL,
189-
email TEXT NOT NULL,
190-
display_name TEXT,
191-
preferred_languages TEXT[] DEFAULT '{typescript,javascript}',
192-
review_reminder_time TIME DEFAULT '09:00',
193-
created_at TIMESTAMPTZ DEFAULT now(),
194-
updated_at TIMESTAMPTZ DEFAULT now()
195-
);
196-
197-
CREATE TABLE snippets (
198-
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
199-
user_id UUID REFERENCES users(id) ON DELETE CASCADE NOT NULL,
200-
title TEXT NOT NULL,
201-
code TEXT,
202-
description TEXT,
203-
language TEXT DEFAULT 'typescript',
204-
tags TEXT[] DEFAULT '{}',
205-
ease_factor FLOAT DEFAULT 2.5,
206-
interval_days INTEGER DEFAULT 1,
207-
repetitions INTEGER DEFAULT 0,
208-
next_review DATE DEFAULT CURRENT_DATE,
209-
created_at TIMESTAMPTZ DEFAULT now(),
210-
updated_at TIMESTAMPTZ DEFAULT now()
211-
);
212-
213-
CREATE TABLE review_logs (
214-
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
215-
snippet_id UUID REFERENCES snippets(id) ON DELETE CASCADE NOT NULL,
216-
user_id UUID REFERENCES users(id) ON DELETE CASCADE NOT NULL,
217-
rating INTEGER NOT NULL CHECK (rating BETWEEN 0 AND 5),
218-
ease_factor_after FLOAT NOT NULL,
219-
interval_after INTEGER NOT NULL,
220-
reviewed_at TIMESTAMPTZ DEFAULT now()
221-
);
222-
223-
CREATE INDEX idx_snippets_next_review ON snippets(user_id, next_review);
224-
CREATE INDEX idx_snippets_user ON snippets(user_id);
225-
CREATE INDEX idx_snippets_tags ON snippets USING GIN(tags);
226-
CREATE INDEX idx_review_logs_snippet ON review_logs(snippet_id);
227-
CREATE INDEX idx_review_logs_user ON review_logs(user_id, reviewed_at);
32+
source .venv/bin/activate
33+
pytest -v
22834
```
22935

23036
---
23137

232-
## API Endpoints
233-
234-
| Method | Endpoint | Description |
235-
|--------|----------|-------------|
236-
| GET | `/api/health` | Health check |
237-
| POST | `/api/review/schedule` | SM-2 spaced repetition scheduling |
238-
| POST | `/api/search` | TF-IDF semantic search |
239-
| POST | `/api/clusters` | K-means topic clustering |
240-
| POST | `/api/snippets/check-duplicate` | Levenshtein duplicate detection |
241-
| POST | `/api/summarize` | Extractive text summarization (MMR) |
242-
243-
---
244-
245-
## Production
38+
# Production
24639

247-
### Frontend — Vercel
40+
| What | URL |
41+
|------|-----|
42+
| Frontend | https://web-two-beta-49.vercel.app |
43+
| Database | https://supabase.com/dashboard/project/dkbsdgsuqqegjvvojfks |
44+
| API | TBD — Railway (Day 19) |
24845

249-
The frontend auto-deploys from the `dev` branch on every push.
46+
## Deploy frontend
25047

251-
**Manual deploy:**
25248
```bash
25349
cd apps/web
25450
npx vercel deploy --prod --yes
25551
```
25652

257-
**Environment variables** are managed in the Vercel dashboard or via:
258-
```bash
259-
npx vercel env ls
260-
npx vercel env add KEY production
261-
```
262-
263-
### Backend — Railway
264-
265-
Coming in Day 19. The FastAPI app deploys from `apps/api/Dockerfile`.
53+
## Query the database
26654

267-
**After Railway setup**, update `NEXT_PUBLIC_API_URL` in Vercel:
26855
```bash
269-
printf "https://your-app.railway.app" | npx vercel env add NEXT_PUBLIC_API_URL production --force
270-
npx vercel deploy --prod --yes
56+
supabase db query "SELECT * FROM users;" --linked
57+
supabase db query "SELECT * FROM snippets;" --linked
58+
supabase db query "SELECT * FROM review_logs;" --linked
27159
```
272-
273-
### Production URLs
274-
275-
| Service | URL |
276-
|---------|-----|
277-
| Frontend | https://web-two-beta-49.vercel.app |
278-
| Backend API | TBD (Railway — Day 19) |
279-
| Database | https://supabase.com/dashboard/project/dkbsdgsuqqegjvvojfks |
280-
281-
---
282-
283-
## Branching Strategy
284-
285-
```
286-
main ← stable, tagged releases (v0.1.0, v0.2.0…)
287-
└── dev ← integration branch, all features merge here
288-
├── sprint-2/feat-clerk-auth
289-
├── sprint-2/feat-api-hooks
290-
└── sprint-2/feat-app-layout
291-
```
292-
293-
Never commit directly to `main` or `dev`. Always work on a `sprint-N/type-description` branch.

0 commit comments

Comments
 (0)