compor-academy/BACKEND.md

Backend foundation

The project now has a small API and a PostgreSQL schema. Video delivery is provider-neutral: lesson_media.provider and lesson_media.external_id describe an external provider without coupling lessons to Panda, Vimeo, or any other service.

Local setup

1. Copy .env.example to .env and use the default local values.
2. Start PostgreSQL with docker compose -f docker-compose.dev.yml up -d postgres.
3. Install dependencies with npm install.
4. Apply the versioned schema with npm run db:migrate.
5. Run the API with npm run dev:api and the frontend with npm run dev.

The API health endpoint is available at http://localhost:3001/api/v1/health. The readiness endpoint verifies PostgreSQL at /api/v1/ready.

Current API

• GET /api/v1/courses returns published courses.
• GET /api/v1/courses/:courseId returns one published course.

Accounts and instructor access

• POST /api/v1/auth/register creates student accounts only.
• POST /api/v1/auth/login creates a seven-day signed session.
• GET /api/v1/auth/me restores an existing session.
• GET, POST, PATCH, and DELETE under /api/v1/manage/courses require an instructor or administrator session. Instructors can manage only their own courses.

To create the first local administrator, set BOOTSTRAP_ADMIN_EMAIL, BOOTSTRAP_ADMIN_PASSWORD, and optionally BOOTSTRAP_ADMIN_NAME, then run npm run db:bootstrap-admin. This command is deliberate and must not be exposed through the public API.

For local demos, npm run db:seed-demo-content imports the original frontend catalogue into PostgreSQL. It requires the bootstrap administrator to exist and skips courses already present.

Public course endpoints return only public lessons and public assets. Enrolment checks, learner progress, and comments will be added in the next milestone.

CI/CD status

Gitea Actions validates every pull request and every push to main by installing locked dependencies, type-checking the frontend and API, and building the frontend. The workflow deliberately does not upload a build artifact: the current Gitea runner does not support upload-artifact@v4, and Portainer builds the deployment image directly from the repository.