[F01] docs and domain lifecycle specification with docker compose execution workflow

[kavix]

Related Issue

Closes #23
Closes #22

Summary

• Added complete Mother & Child Longitudinal Domain Model and Clinical Lifecycles (docs/domain/mother-child-lifecycle.md) resolving Issue followup PR on adding docs and architecture #23 and sub-issue Add Functional Requirements related to to app basic scope #22.
• Added comprehensive Developer Execution and Run Guide (docs/development/run-guide.md) centered on Docker Compose workflows.
• Configured repository linters: .yamllint.yml and .markdownlint.yml.
• Extended GitHub Actions CI workflow with yaml-lint, markdown-lint, secret-scan (gitleaks), and compose-config.
• Extended Makefile with help, lint-md, compose-config, db-up, db-down, db-logs, db-ps, and db-shell.
• Updated README.md with quick navigation to domain specifications and execution guides.

Design / Approach

• Synthesized domain requirements from Issues [F03] Mother Longitudinal Profile #4, [F04] Pregnancy Lifecycle #5, [F07] Child Lifecycle & Profile #8, [F08] Vaccination Management #9, [F09] Growth & Development Monitoring #10, Add Functional Requirements related to to app basic scope #22, [Feature] Implement Child Vaccine Managment #25, [Feature] Child Weight Monitoring #26, [Feature] Implement Child Height Monitoring and Growth Tracking (Birth–5 Years) #27, [Feature] Implement Newly Married Session & Pregnancy Tracking Workflow #28, [Feature] Pregnancy Fetal Heart Rate Monitoring & Alert #29, [Feature] Missed Pregnancy Appointment Detection #30, [Feature] Repeated Fetal Heart Rate Pattern Detection #31, and [Feature] Missing Pregnancy Scan Detection #32 into a cohesive clinical journey.
• Modeled the lifecycle phases: Newly Married Session & Screening, Family Planning Decision Gateway, Pregnancy Preparation Protocols, Active Pregnancy Monitoring (Scans, Hb < 7 alert, FHR anomalies, missed appointments), Delivery & Child linkage, and Pediatric 0–5 years (Vaccines & Growth monitoring).
• Preserved Docker Compose as the primary lightweight local developer workflow with full health checks and Makefile automation.

UI Evidence

• Not applicable

Validation

• Repository validation passes (make validate)
• Markdown linting passes with zero errors on 16 files (make lint-md)
• Docker Compose configuration validated (make compose-config)
• Secret scanning verified (no private keys or .env files tracked)

Impact

• Security: Enhanced secret leak detection via gitleaks in CI.
• Database: PostgreSQL container lifecycle managed cleanly via Docker Compose.
• API: Defined event payloads and state machines for clinical workflows.
• FHIR: Documented HL7 FHIR R4 resource mappings for all maternal and pediatric entities.
• Documentation: Added docs/domain/mother-child-lifecycle.md and docs/development/run-guide.md.

Checklist

• Scope matches the issue
• Synthetic healthcare data only
• No secrets committed
• Authorization impact considered
• Documentation updated where required
• CI passes
• Known limitations documented

[Maleesha101]

Review findings — PR #33

I reviewed the current diff and found the following issues that should be addressed before merge.

🔴 High — Broken developer setup command

File: docs/development/run-guide.md

The Git configuration example contains an unterminated quote:

git config user.email "your-email

Please correct this to a copy/paste-safe command, for example:

git config user.email "your-email@example.com"

This currently makes the documented setup command fail.

🔴 High — HAPI FHIR is coupled to the application PostgreSQL database

File: docker-compose.yml

The HAPI FHIR JPA server is configured against the same adhya PostgreSQL database used by the platform:

SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/${POSTGRES_DB:-adhya}

Please separate FHIR persistence from the application clinical database (for example, a dedicated PostgreSQL database/schema with clearly defined ownership). This will avoid tight coupling between application migrations and FHIR persistence and make backup, migration, and future service separation safer.

Also verify that the WSO2 services actually have the database configuration they require; currently they depend on PostgreSQL health but do not appear to configure a PostgreSQL connection.

🟠 Medium — Gitleaks installation should be supply-chain hardened

File: .github/workflows/ci.yml

The workflow downloads and executes a Gitleaks binary directly with curl:

curl ... gitleaks_8.18.2_linux_x64.tar.gz

For a security-focused repository, please prefer a pinned/reproducible GitHub Action or verify the downloaded artifact checksum/signature before execution. Avoid relying on an unverified external binary.

🟠 Medium — F01 scope has expanded beyond the foundation baseline

Files: docker-compose.yml, Makefile

This PR introduces Siddhi, WSO2 APIM, WSO2 IS, WSO2 MI/FHIR, HAPI FHIR, and OpenChoreo/Choreo Connect into the F01 Compose environment.

The profile approach is useful, but please ensure the documentation clearly distinguishes:

• F01 foundation/local baseline
• later F12 FHIR implementation
• F13 event processing
• F14 API gateway/IAM
• F17 platform deployment

Otherwise F01 becomes responsible for infrastructure that its dependent feature iterations have not yet implemented or validated.

🟡 Medium — Siddhi clinical HTTP ingestion lacks a security boundary

File: siddhi/maternal-alerts.siddhi

The /fhr and /hb HTTP receivers accept patient/pregnancy identifiers and clinical measurements without authentication, authorization, integrity validation, or provenance.

If these endpoints are intentionally only for local development/demo use, document that explicitly and ensure they are not treated as production clinical interfaces.

The eventual architecture should place authenticated event ingestion/validation between clinical services and Siddhi.

🟡 Medium — Clinical rules need source/version provenance

File: docs/domain/mother-child-lifecycle.md

The document defines specific clinical thresholds, schedules, vaccination timing, growth interpretations, and pregnancy protocols.

Please add the authoritative source/version for these rules and distinguish:

• clinical reference
• local policy
• implementation rule
• research/demo assumption

This is important because these values may later become executable clinical alert logic.

Also, please avoid presenting unresolved FHIR mappings as definitively validated. The statement that every domain entity “maps cleanly” to FHIR R4 should be treated as a design baseline until the F12 interoperability work validates the mappings.

Suggested merge criteria

Please address the two high-severity issues at minimum, and clarify the scope/security/provenance items above before merging.

[kavix]

Thanks for the thorough review! I have addressed all the findings in commit 24fb82d:

1. 🔴 Developer setup command: Fixed the unterminated quote in docs/development/run-guide.md to make the git config commands copy/paste safe.
2. 🔴 HAPI FHIR & WSO2 persistence: Decoupled HAPI FHIR into a dedicated adhya_fhir database with automated initialization via docker/postgres/init-fhir-db.sh. Removed unnecessary depends_on: postgres from WSO2, Siddhi, and OpenChoreo, documenting their evaluation preview modes.
3. 🟠 Gitleaks supply-chain hardening: Pinned the Gitleaks download in CI to verify the official SHA-256 checksum before extracting and executing.
4. 🟠 F01 scope clarification: Updated docker-compose.yml, Makefile, and documentation to clearly designate PostgreSQL as the only F01 foundation baseline service, framing the other profiles as feature previews for F12, F13, F14, and F17.
5. 🟡 Siddhi HTTP security boundary: Added architectural notices to siddhi/maternal-alerts.siddhi clarifying that raw HTTP ingestion is strictly for local dev/demo synthetic testing, noting the production gateway/broker requirement.
6. 🟡 Clinical rules provenance & FHIR baseline: Added a 4-tier provenance taxonomy ([CR], [LP], [IR], [RA]) with authoritative citations across docs/domain/mother-child-lifecycle.md, and framed the FHIR mappings as an initial design baseline subject to F12 ADR validation.

All local quality gates and compose checks (make validate, make compose-config) pass cleanly. Ready for another look!