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

.env.example

@@ -5,10 +5,34 @@ APP_ENV=local
 APP_DEBUG=false
 APP_PORT=8080
 
+# PostgreSQL Clinical Database
 POSTGRES_HOST=localhost
 POSTGRES_PORT=5432
 POSTGRES_DB=adhya
 POSTGRES_USER=adhya
 POSTGRES_PASSWORD=change-me
 
+# Siddhi Stream Processor (CEP)
+SIDDHI_HTTP_PORT=8006
+SIDDHI_MGMT_PORT=9091
+
+# WSO2 API Manager 4.3.0
+WSO2_APIM_CONSOLE_PORT=9443
+WSO2_APIM_GATEWAY_HTTPS=8243
+WSO2_APIM_GATEWAY_HTTP=8280
+
+# WSO2 Identity Server 7.0.0 (IAM)
+WSO2_IS_PORT=9444
+
+# WSO2 FHIR / Micro Integrator 4.3.0
+WSO2_FHIR_HTTP_PORT=8290
+WSO2_FHIR_HTTPS_PORT=8253
+WSO2_MI_MGMT_PORT=9164
+
+# HAPI FHIR R4 Server
+FHIR_SERVER_PORT=8080
+
+# OpenChoreo / Choreo Connect Router
+OPENCHOREO_ROUTER_PORT=9095
+
 API_BASE_URL=http://localhost:8080

.github/workflows/ci.yml

@@ -1,6 +1,6 @@
 name: CI
 
-on:
+"on":
   push:
     branches: ["main"]
   pull_request:
@@ -46,3 +46,56 @@ jobs:
             echo "Potential private-key material is tracked."
             exit 1
           fi
+
+  yaml-lint:
+    name: YAML lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install yamllint
+        run: pip install yamllint
+
+      - name: Lint YAML files
+        run: |
+          yamllint -c .yamllint.yml .
+
+  secret-scan:
+    name: Secret scan (gitleaks)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install and run gitleaks
+        shell: bash
+        run: |
+          set -euo pipefail
+          curl -sSfL https://github.com/gitleaks/gitleaks/releases/download/v8.18.2/gitleaks_8.18.2_linux_x64.tar.gz | tar -xz -C /tmp
+          /tmp/gitleaks detect --source . --verbose --no-git
+
+  markdown-lint:
+    name: Markdown lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Run markdownlint
+        uses: DavidAnson/markdownlint-cli2-action@v16
+        with:
+          globs: "**/*.md"
+          config: ".markdownlint.yml"
+
+  compose-config:
+    name: Docker Compose config check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Validate docker-compose.yml
+        run: docker compose config --quiet

.markdownlint.yml

@@ -0,0 +1,20 @@
+# Markdownlint configuration
+# See: https://github.com/DavidAnson/markdownlint#rules--aliases
+
+default: true
+
+# Formatting & Whitespace rules relaxed for documentation repository
+MD001: false  # Heading levels increment
+MD009: false  # Trailing spaces
+MD013: false  # Line length
+MD022: false  # Headings should be surrounded by blank lines
+MD024:
+  siblings_only: true  # Allow duplicate headings in different parent sections
+MD025: false  # Multiple top-level headings in the same document
+MD031: false  # Fenced code blocks surrounded by blank lines
+MD032: false  # Lists surrounded by blank lines
+MD033: false  # Inline HTML (used in alerts and diagrams)
+MD040: false  # Fenced code blocks language specification
+MD041: false  # First line must be top-level heading
+MD058: false  # Tables surrounded by blank lines
+MD060: false  # Table column style

.yamllint.yml

@@ -0,0 +1,22 @@
+extends: default
+
+rules:
+  line-length:
+    max: 160
+    level: warning
+  truthy:
+    allowed-values: ["true", "false", "on"]
+    check-keys: false
+  comments:
+    min-spaces-from-content: 1
+  document-start: disable
+  braces:
+    min-spaces-inside: 0
+    max-spaces-inside: 1
+  brackets:
+    min-spaces-inside: 0
+    max-spaces-inside: 1
+
+ignore: |
+  .git/
+  node_modules/

Makefile

@@ -1,6 +1,33 @@
-.PHONY: validate compose-config db-up db-down
+.PHONY: help validate lint-md compose-config db-up db-down db-logs db-ps db-shell \
+        siddhi-up siddhi-down wso2-up wso2-down fhir-up fhir-down openchoreo-up openchoreo-down \
+        platform-up platform-down
 
-validate:
+help:
+	@echo "Available Makefile targets (Docker Compose workflow):"
+	@echo "  make validate         - Validate foundation files, env safety, and markdown linting"
+	@echo "  make lint-md          - Run markdownlint on all documentation and Markdown files"
+	@echo "  make compose-config   - Validate docker-compose.yml configuration"
+	@echo ""
+	@echo "Core Database:"
+	@echo "  make db-up            - Start local PostgreSQL database container"
+	@echo "  make db-down          - Stop local PostgreSQL database container"
+	@echo "  make db-logs          - Follow PostgreSQL database container logs"
+	@echo "  make db-ps            - Check PostgreSQL container status and health"
+	@echo "  make db-shell         - Open psql shell inside the running database container"
+	@echo ""
+	@echo "Platform Subsystems (Docker Compose Profiles):"
+	@echo "  make siddhi-up        - Start Siddhi CEP Stream Processor (port 8006, 9091)"
+	@echo "  make siddhi-down      - Stop Siddhi CEP Stream Processor"
+	@echo "  make wso2-up          - Start WSO2 API Manager (9443, 8243) & Identity Server (9444)"
+	@echo "  make wso2-down        - Stop WSO2 AM and IS"
+	@echo "  make fhir-up          - Start WSO2 FHIR (MI 8290) and HAPI FHIR R4 (8080)"
+	@echo "  make fhir-down        - Stop FHIR services"
+	@echo "  make openchoreo-up    - Start OpenChoreo / Choreo Connect Router (9095)"
+	@echo "  make openchoreo-down  - Stop OpenChoreo Router"
+	@echo "  make platform-up      - Start the full platform (Postgres, Siddhi, WSO2, FHIR, OpenChoreo)"
+	@echo "  make platform-down    - Stop all platform containers"
+
+validate: lint-md
 	@test -f AGENTS.md
 	@test -f docs/architecture/ARCHITECTURE.md
 	@test -f docs/development/git-workflow.md
@@ -10,12 +37,65 @@ validate:
 	@test -f docs/architecture/ADR/README.md
 	@test ! -f .env
 	@test ! -f .env.local
+	@echo "All foundation and environment checks passed."
+
+lint-md:
+	@if command -v npx >/dev/null 2>&1; then \
+		npx --yes markdownlint-cli2 "**/*.md"; \
+	else \
+		echo "npx not found, skipping local markdownlint (CI will validate)."; \
+	fi
 
 compose-config:
-	docker compose config
+	docker compose --profile platform config --quiet
 
+# Core Database
 db-up:
 	docker compose up -d postgres
 
 db-down:
 	docker compose down
+
+db-logs:
+	docker compose logs -f postgres
+
+db-ps:
+	docker compose ps
+
+db-shell:
+	docker compose exec postgres psql -U $${POSTGRES_USER:-adhya} -d $${POSTGRES_DB:-adhya}
+
+# Siddhi
+siddhi-up:
+	docker compose --profile siddhi up -d postgres siddhi-runner
+
+siddhi-down:
+	docker compose stop siddhi-runner
+
+# WSO2 APIM + IS
+wso2-up:
+	docker compose --profile wso2 up -d postgres wso2-apim wso2-is
+
+wso2-down:
+	docker compose stop wso2-apim wso2-is
+
+# FHIR (WSO2 MI + HAPI FHIR)
+fhir-up:
+	docker compose --profile fhir up -d postgres wso2-fhir hapi-fhir
+
+fhir-down:
+	docker compose stop wso2-fhir hapi-fhir
+
+# OpenChoreo
+openchoreo-up:
+	docker compose --profile openchoreo up -d postgres openchoreo-router
+
+openchoreo-down:
+	docker compose stop openchoreo-router
+
+# Full Platform
+platform-up:
+	docker compose --profile platform up -d
+
+platform-down:
+	docker compose down

README.md

@@ -61,7 +61,14 @@ The original project specification established the technical foundation around *
 
 ---
 
-# 🎯 Problem Statement
+## ⚡ Quick Navigation & Engineering Guides
+
+* 🚀 **[Execution & Run Guide](docs/development/run-guide.md)** — Step-by-step developer guide for running locally with Docker Compose, database management, and running quality checks.
+* 🩺 **[Mother & Child Lifecycle Domain Specification](docs/domain/mother-child-lifecycle.md)** — Comprehensive clinical domain model synthesized from Issues #4, #5, #8, #9, #10, #22, #25, #26, #27, #28, #29, #30, #31, and #32.
+* 🏛️ **[System Architecture](docs/architecture/ARCHITECTURE.md)** — Overall system topology, FHIR mapping, and sequence diagrams.
+* 🌿 **[Git & Branching Workflow](docs/development/git-workflow.md)** — Branch naming, commit conventions, and PR checklist.
+
+---
 
 Maternal and child healthcare requires information to remain available across multiple stages of a patient's healthcare journey.