Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@ This repository contains the Spring Boot backend for the Medical Informatics Pla
- `src/main/java/hbp/mip/configurations`: security, OAuth2/JWT, persistence, OpenAPI, and redirect/filter configuration.
- `src/main/java/hbp/mip/algorithm`: algorithm metadata API/service and Exaflow specification passthrough.
- `src/main/java/hbp/mip/datamodel`: data model API/service backed by Exaflow metadata endpoints.
- `src/main/java/hbp/mip/experiment`: experiment API, service, repository, JPA entity, specifications, and DTOs.
- `src/main/java/hbp/mip/analysis`: analysis API, service, repository, JPA entity, specifications, and DTOs.
- `src/main/java/hbp/mip/user`: active user API/service, user repository, JPA entity, and DTO.
- `src/main/java/hbp/mip/folder`: experiment folder/set API, service, repository, JPA entities, and DTOs.
- `src/main/java/hbp/mip/study`: analysis folder/set API, service, repository, JPA entities, and DTOs.
- `src/main/java/hbp/mip/utils`: shared logging, JSON/HTTP helpers, claim validation, and exception handling.
- `src/main/resources`: local runtime config, Log4j2 config, and Flyway migrations under `db/migration`.
- `.github/workflows`: release image publishing and EBRAINS mirror automation.
Expand Down Expand Up @@ -55,7 +55,7 @@ The Maven build produces `target/platform-backend.jar`.
mvn test
```

There is currently no committed `src/test/java` tree. Treat `mvn test` as the baseline smoke check until focused tests are added.
Focused JUnit and MockMvc tests live under `src/test/java`; run them with `mvn test`.

## Lint / Format / Typecheck
```bash
Expand All @@ -74,7 +74,7 @@ mvn clean package
## Architecture Rules
- Put HTTP endpoints in `*API` classes under the owning feature package.
- Put business logic in `*Service` classes; controllers should delegate rather than implement workflows directly.
- Put persistence in Spring Data repositories and JPA `*DAO` entities. Current JPA packages are `hbp.mip.experiment`, `hbp.mip.user`, and `hbp.mip.folder` (list them in `PersistenceConfiguration` when adding another).
- Put persistence in Spring Data repositories and JPA `*DAO` entities. Current JPA packages are `hbp.mip.analysis`, `hbp.mip.user`, and `hbp.mip.study` (list them in `PersistenceConfiguration` when adding another).
- Put API/request/response shapes in `*DTO` records or DTO classes close to the feature package.
- Put cross-cutting helpers in `hbp.mip.utils` only when they are genuinely shared.
- Put security, persistence, OpenAPI, and web filter wiring in `hbp.mip.configurations`.
Expand Down Expand Up @@ -113,10 +113,10 @@ mvn clean package
## Security and Privacy Rules
- Never commit secrets, tokens, keys, cookies, credentials, or private environment values.
- Never print secrets in logs or final reports.
- Treat auth, authorization claims, CSRF, token exposure, migrations, data deletion, and experiment execution as human-review areas.
- Treat auth, authorization claims, CSRF, token exposure, migrations, data deletion, and analysis execution as human-review areas.
- Preserve OAuth2 login and bearer-token behavior unless the task explicitly changes auth.
- Preserve dataset and experiment access checks in `ClaimUtils` and `ExperimentService`.
- Review logs carefully when touching experiment execution, active user token handling, or external service calls.
- Preserve dataset and analysis access checks in `ClaimUtils` and `AnalysisService`.
- Review logs carefully when touching analysis execution, active user token handling, or external service calls.

## PR Expectations
Every agent change should include:
Expand Down
3 changes: 3 additions & 0 deletions docs/context/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,3 +14,6 @@ This directory contains durable context for humans and AI coding agents working

## How to use this context
Start with `AGENTS.md`, then read the files here that match the task. For code changes, check `architecture.md`, `module-index.md`, `commands.md`, `testing.md`, and `risk-register.md` before editing.

See [terminology migration](../terminology-migration.md) for the coordinated API,
database and UI contract change, rollout, rollback, and data-model error mapping.
20 changes: 11 additions & 9 deletions docs/context/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ This is a backend service for the Medical Informatics Platform. It is a Java 21
## High-Level Structure
The application entrypoint is `hbp.mip.MIPApplication`. APIs are grouped by feature package:

- `algorithm`: runs analyses through Exaflow (for the `experiment` package) and exposes Exaflow's inputdata, preprocessing and algorithm specifications (`/specifications/*`).
- `algorithm`: runs analyses through Exaflow (for the `analysis` package) and exposes Exaflow's inputdata, preprocessing and algorithm specifications (`/specifications/*`).
- `datamodel`: exposes data models and dataset metadata from Exaflow, filtered by user claims when authentication is enabled.
- `experiment`: creates, lists, updates, deletes, and executes experiments; persists experiment records in PostgreSQL.
- `analysis`: creates, lists, updates, deletes, and executes analyses; persists analysis records in PostgreSQL.
- `user`: resolves the active user from OAuth2/OIDC or JWT authentication and persists user profile/NDA state.
- `configurations`: configures security, OAuth2/OIDC, JWT authority mapping, persistence, Flyway, OpenAPI, and SPA redirects.
- `utils`: shared HTTP, JSON, logging, claim, resource, and exception utilities.
Expand All @@ -28,7 +28,7 @@ flowchart TD
- HTTP requests enter controllers named `*API`.
- Controllers create a `hbp.mip.utils.Logger` with active user and endpoint context, then delegate to services.
- Services enforce business rules, authorization checks, external calls, and persistence workflows.
- Repositories and JPA `*DAO` entities handle database access for users and experiments.
- Repositories and JPA `*DAO` entities handle database access for users and analyses.
- DTOs are returned from controllers as API response shapes.
- Exceptions are mapped by `ControllerExceptionHandler`.

Expand All @@ -47,17 +47,17 @@ Persistence is configured in `PersistenceConfiguration`.

- Data source properties come from `spring.datasource`.
- Flyway runs at startup through a `flyway` bean.
- JPA scans `hbp.mip.experiment` and `hbp.mip.user`.
- Existing migration `V1__InitialSchema.sql` creates `user` and `experiment` tables.
- `V3__ExperimentRunDrafts.sql` creates `experiment_run`, which keeps unsaved studio run results until they are saved or expire.
- JPA scans `hbp.mip.analysis` and `hbp.mip.user`.
- Existing migration `V1__InitialSchema.sql` creates `user` and `analysis` tables.
- `V3__ExperimentRunDrafts.sql` creates `analysis_run`, which keeps unsaved studio run results until they are saved or expire.
- Hibernate is configured with `ddl-auto: validate`, so schema changes should be made through Flyway migrations.

## API Layer
The servlet context path is `/services`. Main endpoints include:

- `/algorithms`
- `/data-models`
- `/experiments` (`/experiments/preview` computes without storing, `/experiments/runs` computes and keeps the result, `POST /experiments` saves a kept run)
- `/analyses` (`/analyses/preview` computes without storing, `/analyses/runs` computes and keeps the result, `POST /analyses` saves a kept run)
- `/activeUser`

OpenAPI is configured by `OpenApiConfig` and springdoc dependencies.
Expand All @@ -72,11 +72,11 @@ OpenAPI is configured by `OpenApiConfig` and springdoc dependencies.
- Raw authority mapping for claims and Keycloak roles, intentionally without adding a `ROLE_` prefix.
- Anonymous development behavior when `authentication.enabled` is disabled.

Authorization-sensitive logic appears in `ClaimUtils`, `ExperimentService`, `DataModelService`, and active user handling.
Authorization-sensitive logic appears in `ClaimUtils`, `AnalysisService`, `DataModelService`, and active user handling.

## Background Work and External Services
- `SpecificationsService` fetches inputdata, preprocessing, and algorithm specifications from Exaflow per request.
- `ExperimentService` starts a background `Thread` for persisted experiment execution.
- `AnalysisService` starts a background `Thread` for persisted analysis execution.
- Data model and algorithm metadata are fetched through `HTTPUtil` using configured Exaflow URLs.

## Config and Environment Model
Expand All @@ -91,3 +91,5 @@ Authorization-sensitive logic appears in `ClaimUtils`, `ExperimentService`, `Dat
- No Docker Compose or local database bootstrap file found.
- No dedicated Java lint/formatter/static-analysis command found.
- External service contracts for Exaflow are inferred from URLs and DTOs, not from a committed schema.

V6 renames domain tables and payload columns; see [the migration contract](../terminology-migration.md).
2 changes: 1 addition & 1 deletion docs/context/code-review-checklist.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
- [ ] No secrets are committed.
- [ ] Sensitive values are not logged.
- [ ] Auth/authz behavior is preserved or explicitly reviewed.
- [ ] Dataset and experiment access checks are preserved.
- [ ] Dataset and analysis access checks are preserved.
- [ ] Token exposure and CSRF behavior are reviewed if touched.

## Maintainability
Expand Down
2 changes: 1 addition & 1 deletion docs/context/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ target/platform-backend.jar
mvn test
```

There is no committed `src/test/java` tree. This command currently functions as the baseline Maven test phase/smoke check.
Focused JUnit and MockMvc tests live under `src/test/java`.

## Lint
```bash
Expand Down
6 changes: 3 additions & 3 deletions docs/context/conventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
- Repositories use the `*Repository` suffix.
- JPA entities use the `*DAO` suffix.
- API/request/response shapes use the `*DTO` suffix, often as Java records.
- Feature modules are grouped by package: `algorithm`, `datamodel`, `experiment`, and `user`.
- Feature modules are grouped by package: `algorithm`, `datamodel`, `analysis`, and `user`.

### Backend Layering
- Controllers accept HTTP input, create user/action logs, and delegate to services.
Expand All @@ -26,7 +26,7 @@
### Logging
- User-facing actions use `hbp.mip.utils.Logger`.
- Logs include username, endpoint, and message.
- Existing code logs some request and experiment details; avoid expanding sensitive logging.
- Existing code logs some request and analysis details; avoid expanding sensitive logging.

### Configuration
- Spring properties are defined in `src/main/resources/application.yml`.
Expand All @@ -42,7 +42,7 @@
### Persistence
- Flyway owns migrations.
- Hibernate validates schema with `ddl-auto: validate`.
- Current JPA repositories/entities are in `experiment` and `user`.
- Current JPA repositories/entities are in `analysis` and `user`.

### Agent Tool and Token Budget
- Agents should use focused repository inspection commands and avoid dumping broad context.
Expand Down
Loading
Loading