|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +This file provides guidance to AI agents when working with code in this repository. |
| 4 | + |
| 5 | +## What This Service Does |
| 6 | + |
| 7 | +`audit-manager` is a MOSIP kernel microservice that provides a centralised, tamper-evident audit trail for the entire MOSIP identity platform. Every other MOSIP service (Registration Processor, ID Authentication, Resident Services, Pre-Registration, etc.) calls this service's single POST endpoint to persist an audit event. The service performs no business logic beyond validating the incoming record and writing it to the `audit.app_audit_log` PostgreSQL table. |
| 8 | + |
| 9 | +## Build & Test Commands |
| 10 | + |
| 11 | +All Maven commands must be run from the `kernel/` directory (the Maven multi-module root). |
| 12 | + |
| 13 | +```bash |
| 14 | +# Full build, skip tests and GPG signing (standard dev build) |
| 15 | +cd kernel && mvn install -DskipTests=true -Dmaven.javadoc.skip=true -Dgpg.skip=true |
| 16 | + |
| 17 | +# Build and run all tests |
| 18 | +cd kernel && mvn install -Dmaven.javadoc.skip=true -Dgpg.skip=true |
| 19 | + |
| 20 | +# Run tests for a single module |
| 21 | +cd kernel && mvn test -pl kernel-auditmanager-service -Dgpg.skip=true |
| 22 | + |
| 23 | +# Run a single test class |
| 24 | +cd kernel && mvn test -pl kernel-auditmanager-service -Dtest=AuditServiceTest -Dgpg.skip=true |
| 25 | + |
| 26 | +# Generate OpenAPI JSON (starts service on port 8090, generates JSON, then stops) |
| 27 | +cd kernel && mvn verify -pl kernel-auditmanager-service -P openapi-doc-generate-profile -Dgpg.skip=true |
| 28 | + |
| 29 | +# SonarQube analysis |
| 30 | +cd kernel && mvn verify -P sonar -Dsonar.login=<token> -Dgpg.skip=true |
| 31 | +``` |
| 32 | + |
| 33 | +Tests use H2 in-memory with schema `AUDIT` auto-created at startup. No external dependencies needed to run tests. |
| 34 | + |
| 35 | +## Module Structure |
| 36 | + |
| 37 | +The project is a two-module Maven build under `kernel/`: |
| 38 | + |
| 39 | +| Module | Purpose | |
| 40 | +|--------|---------| |
| 41 | +| `kernel-auditmanager-api` | Shared library: JPA entity, repository, request DTO, validation logic (`AuditUtils`), `AuditHandlerImpl`, and builder | |
| 42 | +| `kernel-auditmanager-service` | Runnable Spring Boot service: REST controller, service layer, auth wiring, exception handler, Swagger config | |
| 43 | + |
| 44 | +`kernel-auditmanager-service` depends on `kernel-auditmanager-api` as a runtime dependency. External MOSIP services that want to log audits programmatically (not via HTTP) can embed `kernel-auditmanager-api` as a library dependency. |
| 45 | + |
| 46 | +## Request Flow |
| 47 | + |
| 48 | +``` |
| 49 | +POST /v1/auditmanager/audits |
| 50 | + → AuditManagerController (service module) |
| 51 | + → AuditManagerServiceImpl (service module) |
| 52 | + → AuditHandlerImpl.addAudit() (api module) |
| 53 | + → AuditUtils.validateAudit() (validates all fields, throws KER-AUD-001 on failure) |
| 54 | + → AuditRepository.save() (JPA → audit.app_audit_log) |
| 55 | + ← ResponseWrapper<AuditResponseDto> { status: true } |
| 56 | +``` |
| 57 | + |
| 58 | +The controller wraps requests in MOSIP's `RequestWrapper<AuditRequestDto>` and responses in `ResponseWrapper<AuditResponseDto>`. The response body's `status` field is always `true` on success. |
| 59 | + |
| 60 | +## Database |
| 61 | + |
| 62 | +- **Schema / table:** `audit.app_audit_log` |
| 63 | +- **Primary key:** `log_id` (UUID, auto-generated) |
| 64 | +- **DDL strategy:** `spring.jpa.hibernate.ddl-auto=none` — schema is managed by scripts in `db_scripts/mosip_audit/` and upgrade scripts in `db_upgrade_scripts/` |
| 65 | +- **Production:** PostgreSQL; connection URL injected via `${audit_database_url}` at runtime from Spring Cloud Config |
| 66 | +- **Local dev:** H2 in-memory (`application-local.properties`); H2 console available at `/admin/h2-console/` |
| 67 | +- **Tests:** H2 in-memory, schema auto-created via `INIT=CREATE SCHEMA IF NOT EXISTS AUDIT` in the JDBC URL; `schema.sql` in main resources initialises the table for local/dev profiles |
| 68 | + |
| 69 | +## Configuration & Profiles |
| 70 | + |
| 71 | +Spring Cloud Config is the source of truth for production config (external `mosip-config` repo, files `application-default.properties` and `kernel-default.properties`). The service name is `kernel-auditmanager-service`. |
| 72 | + |
| 73 | +Local profiles in `kernel/kernel-auditmanager-service/src/main/resources/`: |
| 74 | + |
| 75 | +| Profile | DB | Config server | |
| 76 | +|---------|-----|---------------| |
| 77 | +| `dev` | PostgreSQL at `dev.mosip.net:30090` | disabled (`spring.cloud.config.enabled=false`) | |
| 78 | +| `local` | H2 in-memory | disabled | |
| 79 | + |
| 80 | +Active profile is set in `bootstrap.properties` (`spring.profiles.active=dev`) or overridden at runtime via the `active_profile_env` Docker env var. |
| 81 | + |
| 82 | +## Authentication & Authorisation |
| 83 | + |
| 84 | +The service uses `kernel-auth-adapter` (loaded at runtime via `iam_adapter_url_env` in Docker) to validate MOSIP Bearer tokens. The adapter is added to the classpath via `-Dloader.path`. |
| 85 | + |
| 86 | +Roles permitted to call `POST /audits` are configured via: |
| 87 | +```properties |
| 88 | +mosip.role.auditmanager.postaudits=INDIVIDUAL,REGISTRATION_ADMIN,REGISTRATION_ADMIN_GENERAL,REGISTRATION_ADMIN_ALL_INDIVIDUAL |
| 89 | +``` |
| 90 | +These roles are bound in `AuthorizedRolesDTO` and injected into the security config. |
| 91 | + |
| 92 | +## Docker & Deployment |
| 93 | + |
| 94 | +The container runs as user `mosip` (UID 1001) on port `8081`. The servlet context path is `/v1/auditmanager`. |
| 95 | + |
| 96 | +Runtime environment variables expected by the container: |
| 97 | + |
| 98 | +| Variable | Purpose | |
| 99 | +|----------|---------| |
| 100 | +| `active_profile_env` | Spring active profile | |
| 101 | +| `spring_config_label_env` | Git branch for Spring Cloud Config | |
| 102 | +| `spring_config_url_env` | Spring Cloud Config server URL | |
| 103 | +| `iam_adapter_url_env` | URL to download `kernel-auth-adapter.jar` | |
| 104 | +| `loader_path_env` | Directory for additional JARs (auth adapter) | |
| 105 | + |
| 106 | +JVM flags are hardcoded in the Dockerfile `CMD`: ZGC with generational mode (`-XX:+UseZGC -XX:+ZGenerational`). Additional JVM tuning is provided via the Helm value `additionalResources.javaOpts` (passed as `JDK_JAVA_OPTIONS`) with a full ZGC tuning profile (heap `-Xms1875m -Xmx3200m`, metaspace limits, GC thread counts, etc.) — see `helm/auditmanager/values.yaml`. |
| 107 | + |
| 108 | +Helm chart is in `helm/auditmanager/`. Install via `deploy/install.sh [kubeconfig]` which deploys into the `kernel` namespace with Istio injection enabled. Chart version for develop is `0.0.1-develop`. |
| 109 | + |
| 110 | +## CI/CD |
| 111 | + |
| 112 | +GitHub Actions (`.github/workflows/push-trigger.yml`) uses reusable workflows from `mosip/kattu@master-java21`: |
| 113 | +1. **build-maven-audit-manager** — Maven build at `./kernel/` |
| 114 | +2. **publish_to_nexus** — publishes SNAPSHOT artifacts (skipped on master, PRs, and releases) |
| 115 | +3. **build-dockers** — builds and pushes `mosipqa/kernel-auditmanager-service` image |
| 116 | +4. **sonar_analysis** — SonarQube analysis via sonarcloud.io (skipped on PRs) |
| 117 | + |
| 118 | +Triggers: pushes to `MOSIP*`, `develop*`, `master`, `1.*`, `release*` branches. |
| 119 | + |
| 120 | +## Version Management |
| 121 | + |
| 122 | +The project version follows `kernel/pom.xml`. All three pom files (`kernel/pom.xml`, `kernel-auditmanager-api/pom.xml`, `kernel-auditmanager-service/pom.xml`) must carry the same version. Internal dependency version properties (`kernel.core.version`, `kernel.audit-api.version`, etc.) are also kept in sync. When bumping versions, update all occurrences of the SNAPSHOT string across all three files. |
0 commit comments