From 45cbbfa6141536520605fe45ebf7c3891efe6c8c Mon Sep 17 00:00:00 2001 From: anushasunkada Date: Sun, 26 Apr 2026 20:30:37 +0530 Subject: [PATCH 1/2] Added AGENTS.md file Signed-off-by: anushasunkada --- AGENTS.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..948ba5107d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,96 @@ +# AGENTS.md + +This file provides guidance to AI agent when working with code in this repository. + +## Build Commands + +All commands must be run from inside the `registration/` directory (the Maven parent project). + +```bash +# Full build (skip tests and GPG signing) +cd registration && mvn clean install -Dgpg.skip -DskipTests + +# Build with tests +cd registration && mvn clean install -Dgpg.skip + +# Build a single module +cd registration && mvn clean install -Dgpg.skip -DskipTests -pl registration-services + +# Run tests in a specific module +cd registration && mvn test -pl registration-services + +# Run a single test class +cd registration && mvn test -pl registration-services -Dtest=PacketHandlerServiceTest + +# Sonar analysis +cd registration && mvn verify sonar:sonar -Psonar -Dgpg.skip -DskipTests +``` + +**Requirements:** JDK 21.0.3, Maven 3.9.6 + +## Module Architecture + +The project is a Maven multi-module build under `registration/`: + +| Module | Role | +|---|---| +| `registration-api` | SPI interfaces for pluggable hardware (document scanner, geo-position) | +| `registration-api-stub-impl` | No-op stub implementations of those SPIs for development/testing | +| `registration-services` | All business logic, data access, sync, packet handling — no UI dependencies | +| `registration-client` | JavaFX desktop UI; depends on `registration-services` | +| `registration-test` | End-to-end automation tests using a real running client | +| `ref-impl/` | Reference hardware implementations (commented out of parent pom by default) | + +## Key Architectural Patterns + +### Spring Context Bootstrap +`ClientApplication` (JavaFX `Application` subclass) bootstraps Spring via `AnnotationConfigApplicationContext(AppConfig.class)` during JavaFX `init()`. Spring beans are not available before this point. `SessionContext.setApplicationContext()` stores the context for static access throughout the app. + +### Configuration Loading Order +`DaoConfig` runs first — it initializes the embedded Apache Derby database (encrypted with a machine-specific key via TPM or software fallback), then loads all `GlobalParam` rows from Derby into `ApplicationContext.applicationMap`. Properties in `mosip-application.properties` provide defaults; the DB values override at runtime after sync. + +### Offline-First with Sync Jobs +The client operates fully offline using local Derby. Quartz-scheduled jobs (defined in `jobs/impl/`) periodically sync with the MOSIP server when online: +- `MasterSyncJob` — pulls master data (locations, document types, etc.) +- `PublicKeySyncJob` / `KeyPolicySyncJob` — key material sync +- `RegistrationPacketSyncJob` / `RegistrationPacketUploadJob` — packet status and upload +- `UserDetailServiceJob` — operator details +- `SynchConfigDataJob` — global parameters + +### Registration Packet Flow +1. UI controllers in `registration-client` collect demographic/biometric data into DTOs +2. `PacketHandlerServiceImpl` assembles everything using `commons-packet` library's `PacketWriter` +3. Packet is encrypted client-side via `ClientCryptoFacade` (TPM-backed if available) +4. `PacketSynchServiceImpl` syncs packet status; `PacketUploadServiceImpl` uploads to server + +### JavaFX UI Structure +- `ClientPreLoader` shows a splash screen while `ClientApplication.init()` runs the heavy Spring boot + initial sync +- `Initialization` is the true `main()` entry point (configured as jar manifest `Main-Class`) +- FXML files under `registration-client/src/main/resources/fxml/` are paired with `@Component` controller classes +- `BaseController` provides common navigation helpers; all screen controllers extend it +- `GenericController` drives the dynamic registration form, rendering fields from `IdentitySchema` (downloaded from server and stored in Derby) + +### Biometric Device Integration (MDM) +`MosipDeviceSpecificationFactory` discovers SBI-compliant biometric devices by scanning localhost ports at startup. Device interaction goes through `BioServiceImpl` → MDM spec DTOs in `mdm/`. The SPI in `registration-api` allows injecting alternative scanner/geo-position implementations. + +### AOP Security +`AuthenticationAdvice` and `ResponseSignatureAdvice` in `util/advice/` intercept service calls annotated with `@PreAuthorizeUserId` to enforce that the logged-in operator has the required role before executing sensitive operations. + +### Local Database +Apache Derby embedded DB. Schema lives in `registration-services/src/main/resources/sql/` with versioned migration scripts. `SoftwareUpdateHandler.updateDerbyDB()` runs migrations on startup by comparing the installed version against applied scripts. + +## Configuration + +- Application properties: `registration-services/src/main/resources/props/mosip-application.properties` (defaults only; runtime values come from DB after sync) +- External runtime config is pulled from `mosip-config` repo on the MOSIP server (URL configured via `mosip.hostname`) +- `mosip.hostname` and related server URLs must be set in the DB / properties before the client can sync + +## End-to-End Automation Tests (`registration-test`) + +These are UI-level tests that drive a running Registration Client instance. They are not standard unit tests — they require a live client and a configured environment. + +Configure `registration-test/src/main/resources/config.properties` with operator credentials and environment details, then run via the packaged JAR per the `README.txt` in that directory. + +## Sonar Coverage Exclusions + +DTOs, entities, repositories, FXML controllers, enums, and UI utility classes are excluded from coverage analysis (see `sonar.coverage.exclusions` in the parent `pom.xml`). Focus unit test efforts on `service/`, `jobs/`, `validator/`, and `util/` packages. From ef02d11356b84e635bbc95869605b911287e2f80 Mon Sep 17 00:00:00 2001 From: Anusha Sunkada Date: Thu, 25 Jun 2026 00:18:35 +0530 Subject: [PATCH 2/2] Update AGENTS.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> Signed-off-by: Anusha Sunkada --- AGENTS.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 948ba5107d..3f65f6f046 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -44,12 +44,15 @@ The project is a Maven multi-module build under `registration/`: ## Key Architectural Patterns ### Spring Context Bootstrap + `ClientApplication` (JavaFX `Application` subclass) bootstraps Spring via `AnnotationConfigApplicationContext(AppConfig.class)` during JavaFX `init()`. Spring beans are not available before this point. `SessionContext.setApplicationContext()` stores the context for static access throughout the app. ### Configuration Loading Order + `DaoConfig` runs first — it initializes the embedded Apache Derby database (encrypted with a machine-specific key via TPM or software fallback), then loads all `GlobalParam` rows from Derby into `ApplicationContext.applicationMap`. Properties in `mosip-application.properties` provide defaults; the DB values override at runtime after sync. ### Offline-First with Sync Jobs + The client operates fully offline using local Derby. Quartz-scheduled jobs (defined in `jobs/impl/`) periodically sync with the MOSIP server when online: - `MasterSyncJob` — pulls master data (locations, document types, etc.) - `PublicKeySyncJob` / `KeyPolicySyncJob` — key material sync @@ -58,12 +61,14 @@ The client operates fully offline using local Derby. Quartz-scheduled jobs (defi - `SynchConfigDataJob` — global parameters ### Registration Packet Flow + 1. UI controllers in `registration-client` collect demographic/biometric data into DTOs 2. `PacketHandlerServiceImpl` assembles everything using `commons-packet` library's `PacketWriter` 3. Packet is encrypted client-side via `ClientCryptoFacade` (TPM-backed if available) 4. `PacketSynchServiceImpl` syncs packet status; `PacketUploadServiceImpl` uploads to server ### JavaFX UI Structure + - `ClientPreLoader` shows a splash screen while `ClientApplication.init()` runs the heavy Spring boot + initial sync - `Initialization` is the true `main()` entry point (configured as jar manifest `Main-Class`) - FXML files under `registration-client/src/main/resources/fxml/` are paired with `@Component` controller classes @@ -71,12 +76,15 @@ The client operates fully offline using local Derby. Quartz-scheduled jobs (defi - `GenericController` drives the dynamic registration form, rendering fields from `IdentitySchema` (downloaded from server and stored in Derby) ### Biometric Device Integration (MDM) + `MosipDeviceSpecificationFactory` discovers SBI-compliant biometric devices by scanning localhost ports at startup. Device interaction goes through `BioServiceImpl` → MDM spec DTOs in `mdm/`. The SPI in `registration-api` allows injecting alternative scanner/geo-position implementations. ### AOP Security + `AuthenticationAdvice` and `ResponseSignatureAdvice` in `util/advice/` intercept service calls annotated with `@PreAuthorizeUserId` to enforce that the logged-in operator has the required role before executing sensitive operations. ### Local Database + Apache Derby embedded DB. Schema lives in `registration-services/src/main/resources/sql/` with versioned migration scripts. `SoftwareUpdateHandler.updateDerbyDB()` runs migrations on startup by comparing the installed version against applied scripts. ## Configuration