Canvas School Portal Development
Expert guidance for building and maintaining a Canvas-style educational SaaS platform for the Concentrate.ai hiring assessment.
Project Context
This is a school portal platform with three user roles (Admin, Teacher, Student) supporting class management, lesson publication, assignment submission, and grading.
**Key Constraints:**
Only use dependencies in `package.json` (Radix/shadcn UI components allowed)90%+ test coverage required (100% aspirational)No `any` types allowed (ESLint enforced)Must implement OAuth (Google, Microsoft, or GitHub)Architecture Overview
Tech Stack
**Frontend:** Next.js 15, React 19, TailwindCSS, Radix UI**Backend:** Fastify, TypeScript, Zod validation**Database:** PostgreSQL 17 with Kysely ORM**Caching:** Redis**Testing:** Vitest, React Testing Library, Supertest, PlaywrightUser Roles
**Admin:** Manage teachers, students, and teacher groups**Teacher:** Manage classes, assignments, grading**Student:** View classes, submit assignments, view gradesDatabase Connection
PostgreSQL: `localhost:5432` (database: `concentrate-quiz`, user/pass: `postgres/postgres`)Redis: `localhost:6379`Development Guidelines
1. Code Standards
**TypeScript:**
**Zero `any` types** - builds will fail if presentUse Zod for runtime validationKysely for type-safe database queriesStrict typing for all functions and components**Formatting:**
Single quotes, 2-space tabs, 80 char widthPrettier with Tailwind CSS pluginTrailing commas (ES5)**React:**
React 19 hooks patternsNo prop-types (TypeScript only)Server components where possible2. Testing Requirements
**Coverage Targets:**
90%+ coverage required100% aspirational with documented exceptions**Test Types:**
Unit tests for all service methodsIntegration tests for all API endpoints (59 currently passing)Component tests for key UI featuresE2E tests with Playwright for critical user flows**Commands:**
```bash
npm run test # All tests
npm run coverage # Coverage report
npm run test:e2e # Playwright E2E
npm run test <path> # Specific test file
```
3. Authentication Implementation
**Requirements:**
JWT tokens with HTTP-only cookiesRefresh token rotationAt least one OAuth provider (Google, Microsoft, or GitHub)All API endpoints must be protected**Current Status:**
JWT auth with refresh rotation: ✅ CompleteGoogle OAuth: 🔄 In progress4. School Statistics API
Public endpoints under `/api/v0/stats/`:
`GET /average-grades` - Overall average`GET /average-grades/:id` - Class average`GET /teacher-names` - All teachers`GET /student-names` - All students`GET /classes` - All classes`GET /classes/:id` - Students in class5. Database Operations
**Starting Services:**
```bash
docker-compose up -d # Start PostgreSQL + Redis
docker-compose ps # Check health
docker-compose down # Stop services
```
**Schema Management:**
Use Kysely migrationsType-safe queries onlyDocument schema changes in session logs6. Adding New Features
**Process:**
1. Check `docs/planning/SPECS.md` for requirements
2. Review latest session status (`docs/sessions/SESSION_*_STATUS.md`)
3. Write tests first (TDD approach)
4. Implement feature with strict typing
5. Run full test suite (`npm run test`)
6. Update session documentation
7. Deployment Requirements
**Docker:**
Single root-level Dockerfile for entire stackDocker Compose for local developmentProduction: Nginx reverse proxy + Certbot SSL**CI/CD Pipeline Must:**
Run all testsEnforce 90%+ coverageBuild all servicesPush to Docker Hub8. File References
When working on features, reference these documents:
Full specs: `docs/planning/SPECS.md`Testing guide: `TESTING.md`Session history: `docs/sessions/`Latest status: `docs/sessions/SESSION_13_STATUS.md`Common Tasks
Adding a New API Endpoint
1. Define route in `src/routes/`
2. Create service method in `src/services/`
3. Add Zod schema validation
4. Write integration test in `tests/integration/`
5. Ensure 90%+ coverage
Adding a New Component
1. Create component in `src/components/`
2. Use Radix UI primitives where applicable
3. Add TypeScript props interface
4. Write component tests
5. Follow Tailwind styling patterns
Debugging Database Issues
1. Check service health: `docker-compose ps`
2. View logs: `docker-compose logs postgres`
3. Connect directly: `psql -h localhost -p 5432 -U postgres -d concentrate-quiz`
4. Review Kysely query logs
Extra Credit Feature
Implement an LLM-powered chatbot with:
API calls to LLM providerApp-level context awarenessBasic Q&A about platform featuresImportant Notes
**Current Status:** Backend API complete (42 endpoints, 95%+ coverage), Google OAuth in progress**No `any` types:** This is a hard requirement enforced by ESLint**Test coverage:** CI/CD enforces 100% (90%+ with documented exceptions)**Dependencies:** Only add from approved list or Radix/shadcn UI componentsSubmission Requirements
Prepare 5-10 minute video covering:
Application walkthrough (UI and features)Architecture decisionsTesting approach and coverageDeployment setup