📜 SSC Insight
A warm-paper SSC CGL Tier 2 mock tracker built with modern web technologies. Opens to a public landing page; signed-in visitors go straight to their private dashboard.
📑 Table of Contents
🎨 Design Philosophy
- Aesthetic: Cream paper, charcoal ink, and terracotta actions.
- Typography: Source Serif 4 for headings, DM Sans for controls.
- Layout: Square panels, clean borders, and mobile-first responsive previews.
- Documentation: See
DESIGN.md and PRODUCT.md for detailed guidelines.
[!NOTE]
Mobile previews in the repository use illustrative data. The application does not seed mock attempts by default.
🗄️ Database & Authentication
The database is PostgreSQL on Neon, accessed exclusively through Prisma and the Neon serverless adapter in Next.js Node route handlers.
- Application Schema:
ssc_insight (contains MockAttempt, ordered SubjectResult rows, and per-user TrackerSettings).
- Auth Schema: Managed entirely by Neon. Application migrations never touch the Auth schema.
[!WARNING]
The private-account migration assigns existing shared mocks to a verified admin identity. Firebase records remain untouched and are not copied automatically. Legacy JSON backups (v1–v4) remain importable; new exports use format v5.
💻 Run Locally
Requires Node.js 22.20+ or Node.js 24. Prisma Client generates automatically on installation.
# 1. Install dependencies
npm ci
# 2. Authenticate and link to Neon
neon login
neon link --org-id <YOUR_ORG_ID> --project-id <YOUR_PROJECT_ID> --branch production -y
# 3. Deploy local services and pull env vars
neon deploy
# 4. Start development server
npm run dev
[!SECURITY]
Open http://localhost:3000 in your browser. While the dev server can bind to 0.0.0.0 for network access, always use http://localhost:3000 (or your machine's specific LAN address) to ensure OAuth callbacks and redirects preserve the correct Host header and normalize safely. Avoid exposing the dev server to untrusted networks.
🔐 Environment Variables
Copy .env.example or use Neon's environment pull. Never commit real values to version control.
| Variable | Purpose |
|---|
DATABASE_URL | Pooled PostgreSQL runtime connection. |
DATABASE_URL_UNPOOLED | Direct connection used only by Prisma migration commands. |
NEON_AUTH_BASE_URL | Managed Auth URL ending in /auth. |
NEON_AUTH_COOKIE_SECRET | Cryptographically random secret (≥32 characters). |
GOOGLE_AUTH_ENABLED | Set to true after configuring a production Google OAuth client. |
AI_BASE_URL | Optional OpenAI-compatible base URL (defaults to https://api.openai.com/v1). |
AI_API_KEY | Server-only provider key. Blank disables AI. |
AI_MODEL | Provider model ID. Required to enable AI. |
AI_JSON_MODE | true by default. Set false if the provider rejects response_format. |
AI_DAILY_REQUEST_LIMIT | AI requests per user per IST day (default: 30). |
AI_DAILY_TOKEN_LIMIT | Charged tokens per user per IST day (default: 300000). |
AI_MAX_OUTPUT_TOKENS | Per-call output cap (default: 1200). |
AI_TIMEOUT_MS | Provider timeout below the 60-second route limit (default: 45000). |
AI_CREDENTIAL_SECRET | Encrypts user-entered API keys (AES-256-GCM). 64 hex chars or ≥32-char passphrase. |
CRON_SECRET | Bearer token for /api/cron/trash-cleanup. Generate via . |
[!TIP]
Keep every variable server-side. None require a NEXT_PUBLIC_ prefix. Missing Auth configuration fails closed; private records are never returned anonymously.
🗜️ Migrations
npm run db:generate
npm run db:migrate
prisma.config.ts loads Next.js environment files and uses the unpooled connection.
[!CAUTION]
- Do not run
prisma migrate reset.
- Do not target Neon's managed Auth schema.
- Test new SQL migrations on an expiring branch first.
- The Trash migration (
20261103000000_trash) is additive but order-sensitive. Apply it before deploying the matching app revision to prevent query failures or accidental hard-deletes during rollbacks.
🔑 Google Sign-In Setup
Use Neon Auth's Google provider with your own Google OAuth Web application credentials in production.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
