satusehat-service/docs/DEVPLAN.md

Development Plan — service-satusehat

Field	Value
Document Version	1.0
Status	Draft for review
Owner	Backend Engineering — Meninjar
Last Updated	2026-05-13
Horizon	~2 quarters (M1 → M5)

Read this together with PRD.md (the what / why), analysis.qmd (the as-is), and DEVLOG.md (the what happened).

---

1. Guiding Principles

1. Stabilise before extending. The 19 FHIR resources work end-to-end but rest on near-zero tests and an empty gRPC surface. Hardening comes before new features.
2. Pure mappers. No I/O, no env reads inside Map*ToFHIR. Inject from the service layer. This is the EpisodeOfCare pattern applied broadly.
3. One change, one PR, one CI run. No more multi-resource omnibus commits like af32d9c.
4. Audit everything that talks to SATUSEHAT. Outbound calls are regulator-visible artefacts.
5. Production readiness is a checklist, not a feeling. See §6.

---

2. Milestones

M1 — Hardening (Weeks 1–3)

Goal: make the codebase safe to refactor. After M1, every PR runs through CI with linting + tests, the obvious bugs are fixed, and the debug-log noise is gone.

ID	Task	Effort	Owner	Acceptance
T-01	Set up CI (GitHub Actions): go vet, golangci-lint, go test, make audit, make security-check, Docker build	1 d	Backend	PR triggers green pipeline; status checks required for main
T-02	Add golangci-lint.yml config (errcheck, gocritic, gosec, revive, govet)	0.5 d	Backend	make lint returns clean baseline (existing offenders allowlisted, not silenced)
T-03	Unit tests for every Map*ToFHIR (19 resources)	4 d	Backend	Golden-file tests; make test ≥ 60 % coverage on internal/satusehat/usecase/**
T-04	Apply the EpisodeOfCare pattern to the remaining 18 usecases (drop env reads, accept orgID via constructor)	3 d	Backend	No usecase mapper imports os; main.go wires cfg.SatuSehat.OrgID for all
T-05	Replace fmt.Printf debug in pkg/utils/query/** with logger.Debug()	0.5 d	Backend	grep -R "fmt.Printf" pkg/utils/query returns 0
T-06	Make NoOp cache goroutine-safe with sync.RWMutex	0.5 d	Backend	Race-detector tests pass under load
T-07	Delete commented-out Kafka producer + ImagingStudy worker from cmd/api/main.go, or move behind a KAFKA_ENABLED feature flag	0.5 d	Backend	main.go has no commented blocks > 3 lines
T-08	Rename internal/master/role/accses → access	0.5 d	Backend	One renaming commit; all imports updated

Exit criteria: CI required on main, lint clean baseline, FHIR mapper unit-test coverage ≥ 60 %, no debug Printf in pkg/.

---

M2 — Auditability (Weeks 4–5)

Goal: every outbound SATUSEHAT call leaves a row we can defend in a Kemenkes audit.

ID	Task	Effort	Owner	Acceptance
T-10	Design table satusehat_submission	0.5 d	Backend	Columns: id, resource, method, endpoint, request_id, request_body_hash, response_status, response_body_hash, satusehat_resource_id, error_code, created_at, latency_ms, org_id, user_id
T-11	Migration + GORM model + CommandRepository / QueryRepository	1 d	Backend	Goose migration runs; CQRS pair compiles
T-12	Wrap internal/interfaces/satusehat.Client.DoRequest with an audit interceptor (decorator)	1 d	Backend	Every outbound call writes a row; failures still write
T-13	Add request-ID middleware (X-Request-ID propagation, ULID generation if absent)	0.5 d	Backend	All logs + audit rows carry the same request_id
T-14	Retention policy doc — keep submissions for ≥ 25 years per Permenkes 24/2022	0.5 d	Backend / Compliance	docs/RETENTION.md exists and references the regulation
T-15	Health probe /health/satusehat — last successful call within 5 min	0.5 d	Backend	Returns 200 when at least one submission within the window

Exit criteria: Audit rows for every outbound call across all 19 resources, joinable on request_id, retained per policy.

---

M3 — gRPC Catch-up (Weeks 6–8)

Goal: bring the gRPC transport from empty to parity with REST for the four hottest resources.

ID	Task	Effort	Owner	Acceptance
T-20	Author proto/v1/satusehat/{encounter,episodeofcare,condition,observation}.proto	2 d	Backend	make proto generates clean Go code
T-21	Implement gRPC handlers for the four resources reusing the existing services	2 d	Backend	gRPC + REST share the same service layer
T-22	Register handlers in cmd/api/main.go gRPC server	0.5 d	Backend	grpcurl … list shows the four services
T-23	Add buf lint + breaking-change check to CI	0.5 d	Backend	PRs that break protobuf surface fail CI
T-24	Postman → grpcurl examples in docs/api/	0.5 d	Backend	One example call per service in markdown

Exit criteria: Four resources callable via gRPC, behind the same auth, with parity behaviour to REST.

---

M4 — Resilience (Weeks 9–10)

Goal: survive a flaky SATUSEHAT without dropping submissions.

ID	Task	Effort	Owner	Acceptance
T-30	Retry middleware on Client.DoRequest: exponential backoff (250 ms · 2^n, cap 8 s), max 5 attempts, retry on 5xx + network errors only	1 d	Backend	Unit tests with fake transport
T-31	Circuit breaker (sony/gobreaker) per upstream (FHIR, KFA, KYC, Consent, DICOM)	1 d	Backend	Opens after 5 consecutive failures, half-opens after 30 s
T-32	Idempotency key support — caller supplies Idempotency-Key, service dedupes within 24 h via Redis	1 d	Backend	Replays return the original response, not a duplicate submission
T-33	Rate-limit middleware on inbound (Redis token bucket, key by user_id then ip)	1 d	Backend	cfg.Security.RateLimit.RequestsPerMinute enforced
T-34	Refresh-token revocation on logout — persist to revoked_tokens table; check on every refresh (closes TODO at internal/auth/service.go:233)	1 d	Backend	Logout test passes; refresh returns 401 after logout
T-35	Persist KYC verification result locally (closes TODO in kyc/service.go)	0.5 d	Backend	New table kyc_verification; result row on every success
T-36	Standardise cache invalidation in role/master, role/pages, role/permission, role/access — invalidate on every command op	1 d	Backend	TODOs removed; integration test covers stale-cache scenario

Exit criteria: Service tolerates 30 s of SATUSEHAT 5xx without losing a submission; logout truly invalidates; cache is never stale after a write.

---

M5 — Production Rollout (Weeks 11–12)

Goal: from "running on a dev box" to "running in the hospital DC, one instance, watched."

ID	Task	Effort	Owner	Acceptance
T-40	Production docker-compose.prod.yml review with ops; document the external network requirement	0.5 d	Backend / Ops	docs/deployment.md updated; one-shot setup script
T-41	Grafana dashboard JSON (request volume, p50/p95/p99 latency, error rate by code, DB pool, cache hit ratio)	1 d	Backend	Dashboard imports cleanly; screenshot in docs/
T-42	Prometheus alert rules (SATUSEHAT 5xx > 5/min, p95 > 5 s for 5 min, DB pool exhaustion)	0.5 d	Backend / Ops	Rules under deploy/prom/alerts.yaml
T-43	Backup strategy for satusehat_submission and master DB (daily pg_dump, 30-day retention onsite, 1-year offsite encrypted)	0.5 d	Ops	docs/BACKUP.md exists
T-44	DR runbook — what to do when SATUSEHAT is down, when Redis is down, when the DB primary fails	1 d	Backend / Ops	docs/RUNBOOK.md exists
T-45	Soft launch — 1 hospital, 1 day of shadow traffic	1 d	All	No P0 incidents; audit table populated
T-46	GA — promote to all sites that depend on SATUSEHAT submission	0.5 d	All	Stakeholder sign-off

Exit criteria: Service running in production with full observability, alerts, backups, and a runbook.

---

3. Backlog (post-M5, not yet scheduled)

• B-01 Multi-tenant support: one binary, multiple org_ids per request based on JWT claim (depends on T-04 pattern across all 19).
• B-02 Event-driven mode: re-enable the commented-out Kafka producer (cmd/api/main.go:137–141) so that submissions are emitted as events for downstream consumers (data warehouse, BI).
• B-03 Background worker for ImagingStudy DICOM uploads (re-enable cmd/api/main.go:286–300 behind a worker process flag).
• B-04 OpenTelemetry tracing (replace ad-hoc request-id with traceparent).
• B-05 Bulk submission endpoints (POST /v1/Encounter/bundle) for back-fill scenarios.
• B-06 Mobile-friendly DTOs (slimmer JSON than the full FHIR shape).
• B-07 Finish or remove the tools/generate.go code generator.
• B-08 Postman → automated contract tests in CI.

---

4. Risk Register

ID	Risk	Likelihood	Impact	Mitigation
RK-1	Refactor breaks an in-production FHIR resource	Med	High	T-03 unit tests must land before T-04 refactor cascade
RK-2	SATUSEHAT contract changes mid-quarter	Low	High	Contract tests behind a build tag, run nightly against staging
RK-3	Hospital DC ops cannot operate Prometheus stack	Med	Med	Provide a one-shot Compose + Grafana with default dashboards
RK-4	Single instance is a SPOF	High	Med	M5+ plan to run two instances behind nginx; cache is shared so it's safe
RK-5	Audit table grows unbounded	High	Low	Partition by month + offsite archive (T-14)
RK-6	Refresh-token revocation table grows unbounded	Med	Low	TTL cleanup job; keep only until exp + 7 d
RK-7	gRPC contract evolves and breaks mobile clients	Med	Med	T-23 buf breaking-change check

---

5. Dependencies & Coordination

Dependency	Needed by	Status
SATUSEHAT staging credentials	M1+	✓ in .env
Keycloak realm config	M1+	depends on hospital IAM team
External Docker network service-general_default	M5	✓ created by service-general compose
Prometheus + Grafana in hospital DC	M5	⚠ to confirm with ops
Offsite backup target	M5	⚠ to confirm with ops

---

6. Definition of Done (per task)

A task is Done only when:

1. Code merged to main via PR.
2. CI green (lint + test + audit + security-check + Docker build).
3. Tests cover the happy path and at least one error path.
4. docs/DEVLOG.md has a new entry referencing the task ID.
5. If user-visible: docs/PRD.md updated; if architectural: docs/analysis.qmd updated.
6. If touching ops: docs/deployment.md / RUNBOOK.md updated.
7. No new TODO without a backlog ID.

---

7. Cadence

• Daily: 15-min stand-up over chat; update task status in the issue tracker.
• Weekly: 30-min review — what shipped, what's blocked, what's next.
• Per milestone: written retrospective appended to DEVLOG.md with scope decision.