oodikone/AGENTS.md

AGENTS.md

Oodikone is a Docker-based Node.js/TypeScript application for analysing University of Helsinki study data. Main areas are:

• services/frontend: React, Vite, Redux Toolkit, and Material UI.
• services/backend: Express, Sequelize, PostgreSQL, Redis, and BullMQ.
• services/shared: shared types and utilities.
• updater/: Sisu data workers and scheduler.
• e2e/: Playwright e2e tests

Use Node.js 24 or newer. Packages have separate dependencies and lockfiles. Install locally with npm run install:local, or use npm run ci:local for lockfile-exact installs. Docker uses host-mounted locks: update dependencies locally, then run npm run ci:docker; do not install in containers.

Development Rules

• Read nearby code and tests before changing behavior; follow local conventions.
• Keep changes focused and avoid unrelated formatting.
• Reuse services/shared for cross-service types and utilities.
• Never commit .env files, credentials, database dumps, or real student data.
• Use anonymized data. Do not reset real databases, use destructive commands, or use real-data Docker profiles unless explicitly required.
• Treat migrations as production-impacting. They are in services/backend/src/database/migrations_kone, services/backend/src/database/migrations_user, and updater/sis-updater-worker/src/db/migrations; test migration changes against the relevant database service.
• Do not access the database directly (e.g. docker exec into a database container, psql, Adminer, or similar). Go through the application's models or services instead or ask if there is questions about the data.
• Add tests, especially unit tests, when adding or changing behavior.

Local Commands

npm run oodikone       # start the anonymized environment
npm run oodikone:ci    # start the test mode
npm run both           # start Oodikone and the updater
npm run docker:down    # stop containers
docker compose ps      # show service status

The app runs at http://localhost:3000 and Adminer at http://localhost:5050. Follow logs with docker compose logs --follow frontend or docker compose logs --follow backend.

Style And Verification

• TypeScript/JavaScript: 2 spaces, single quotes, no semicolons, trailing commas where valid, 120-character lines.
• Prefer explicit types at package boundaries, API payloads, Redux state, and database interfaces. Avoid any except where needed to contain an untyped external API.
• Run npm run fmt on changed source, npm run lint, and npm run stylelint when CSS changes. Do not bypass the type-aware Oxlint/Oxfmt pre-commit hooks.
• Run the narrowest relevant check, then broader checks as needed:
  • Frontend: npm run build --prefix services/frontend, npm run test:unit --prefix services/frontend, or npm run test:component --prefix services/frontend.
  • Backend: npm run build --prefix services/backend, or npm run test:unit --prefix services/backend, npm run test:services --prefix services/backend, or npm run test:api --prefix services/backend.
  • Shared: npm run test --prefix services/shared.
  • E2E: npm run playwright -- e2e/<spec>.spec.ts.
    • If running docker-compose.ci.yml add env variable CI=true before the e2e npm command. Otherwise some tests fail.
• API, service, component, and E2E tests require Docker; start the relevant environment with npm run oodikone:test or its documented profile. Report any checks that could not run and why.

CI also validates Docker Compose files, Dockerfiles, shell scripts, workflows, and migrations. Keep such changes minimal and validate them locally where practical.