mirror of
https://github.com/UniversityOfHelsinkiCS/oodikone.git
synced 2026-10-12 19:03:39 +03:00
64 lines
3.6 KiB
Markdown
64 lines
3.6 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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.
|