docs: readme

README.md

@@ -1,35 +1,46 @@
-# Nettdetektivene backend
+# Nettdetektivene Backend
 
-## Local configuration
+This is the backend for Nettdetektivene. It is a Kotlin + Spring Boot application that provides the API used by the frontend.
 
-Spring loads optional local config from `.env` and `.env.dev` in the project root.
+To run this properly, check out the full `nettdetektivene` repository. Tests and local development are expected to be run from the main repo, together with Docker.
 
-- `.env`: shared local defaults for the team
-- `.env.dev`: machine-specific developer overrides
-- `src/test/resources/application.properties`: isolated test-only config
+## Architecture
 
-The application code does not contain environment-specific secrets or URLs. Runtime values come from configuration only, and startup fails if required security config is missing.
+The backend is organized by feature.
 
-Both files use standard `KEY=value` property lines. Start by copying:
+- `app` and `app/config`: application setup and shared Spring configuration
+- `iam`: authentication, registration, JWT, and security-related logic
+- `classroom`: classroom management for teachers and pupils
+- `game`: game flow, map stops, tasks, and pupil progress
+- `mystery`: mystery content and teacher mystery management
+- `notification`: inbox, delivery, and notification events
+- `notebook`, `leaderboard`, `medals`, `moderation`, `users`, `xp`: feature-specific domains and APIs
+- `shared`: shared utilities and events
 
-```bash
-cp .env.example .env
-cp .env.dev.example .env.dev
-```
+Features follow the same structure:
 
-## Environment model
+- `api`: controllers and request/response DTOs
+- `application`: service-layer logic
+- `domain`: entities and core domain models
+- `infrastructure`: repositories and persistence details
 
-- Dev: `.env` plus optional `.env.dev`
-- CI: GitHub Actions secrets / environment variables
-- Docker or prod: container environment variables or a secret manager mounted as env
+## Tests
 
-The same property keys are used in every environment, so you do not need to change Kotlin code when moving from local development to CI or production.
+Run backend tests from the main `nettdetektivene` setup with Docker, not from this folder in isolation.
+
+The backend has a mix of:
+
+- unit and service-level tests for business logic
+- integration tests for controllers, persistence, and API behavior
+- Spring Boot test coverage for full application flows
+
+The test suite uses JUnit 5 with Spring Boot test support. There is also JaCoCo coverage reporting configured in Gradle.
 
 ## Formatting
 
-The project now enforces one shared code style for Kotlin and Gradle files through Gradle and CI.
+Formatting is enforced through Spotless.
 
-- Check formatting: `./gradlew spotlessCheck`
-- Apply the project format: `./gradlew spotlessApply`
+- `spotlessCheck`: checks that Kotlin and Gradle files follow the project format
+- `spotlessApply`: applies the project format automatically
 
-`./gradlew check` also runs the formatting check, and GitHub Actions will fail if pushed code does not match the checked-in style.
+Formatting is also part of the Gradle `check` flow, so CI will fail if the code style does not match.