Development Blueprint — Engineering View

1. ⚙️ Tech Stack

Decisions dgn rationale. Reuse existing ALESA foundation maxima — bukan re-invent.

2. 📁 Repository Structure

Monorepo dgn folder modular. Setiap modul ada own folder + own owner.

medieco/
├── README.md
├── docs/
│   ├── decisions/                  # ADR (Architecture Decision Records)
│   ├── runbooks/                   # Ops runbooks per scenario
│   ├── api/                        # OpenAPI specs · MCP schemas
│   └── modules/                    # Per-module spec docs
├── apps/
│   ├── ops/                        # Laravel 11 + Filament 3 (Doctor/Pharmacy/Admin UI)
│   │   ├── app/
│   │   │   ├── Filament/
│   │   │   │   ├── Doctor/         # M4 Doctor PA panels
│   │   │   │   ├── Pharmacy/       # M5 Pharmacy PA panels
│   │   │   │   └── Admin/          # M7 Admin PA panels
│   │   │   ├── Models/
│   │   │   ├── Services/
│   │   │   └── Http/
│   │   ├── database/migrations/    # Doc Zam 11-section Patient + ENC + RX schemas
│   │   ├── resources/views/
│   │   └── routes/
│   ├── patient-pwa/                # Patient mobile PWA (separate Laravel + Livewire)
│   │   ├── app/
│   │   ├── public/manifest.json
│   │   └── public/sw.js
│   └── agents/                     # Python agent runtime
│       ├── pyproject.toml
│       ├── medieco/
│       │   ├── orchestrator/       # LangGraph state machines
│       │   ├── agents/
│       │   │   ├── patient_pa.py   # M1
│       │   │   ├── doctor_pa.py    # M4
│       │   │   ├── pharmacy_pa.py  # M5
│       │   │   ├── admin_pa.py     # M7
│       │   │   └── triage_engine.py
│       │   ├── memory/             # Redis · pgvector wrappers
│       │   ├── guardrails/         # M9 PDPA · HITL · Hallucination
│       │   └── tools/              # MCP tool implementations
│       └── tests/
├── mcp-medix/                      # MCP server (FastAPI)
│   ├── pyproject.toml
│   ├── server.py                   # MCP protocol implementation
│   ├── tools/
│   │   ├── clinical/               # cdss · ddi · symptom-dx · cpg-lookup
│   │   ├── medication/             # npra-stock · dose-calc · halal-filter
│   │   ├── patient/                # fhir-read · vital-stream · history-fetch
│   │   ├── billing/                # icd10-code · einvoice-lhdn · claim-file
│   │   ├── comms/                  # waha-send · pager-api · sms-gw
│   │   └── admin/                  # audit-write · perm-check · feature-flag
│   └── tests/
├── infra/
│   ├── docker/                     # Dockerfile per service
│   ├── docker-compose.yml          # Dev environment
│   ├── docker-compose.prod.yml     # Prod environment
│   ├── ansible/                    # Server provisioning
│   │   ├── playbooks/
│   │   └── roles/
│   ├── terraform/                  # Cloud burst infra (optional)
│   └── k8s/                        # Future: kubernetes manifests
├── shared/
│   ├── proto/                      # Cross-app type definitions
│   ├── constants/                  # Shared enums (triage levels · ICD groups)
│   └── fixtures/                   # Test data · seed data
├── scripts/
│   ├── deploy.sh
│   ├── backup.sh
│   ├── rollback.sh
│   └── db-migrate.sh
├── .github/
│   ├── workflows/
│   │   ├── ci.yml                  # Lint · test · build
│   │   ├── cd-staging.yml
│   │   └── cd-prod.yml
│   ├── CODEOWNERS
│   └── PULL_REQUEST_TEMPLATE.md
├── .env.example
├── .gitignore
└── compose.override.yml.example

3. 🌿 Branch Strategy

Gitflow-lite. Trunk-based dgn release branches.

main                            # production-ready · auto-deploy ke prod
├── develop                     # integration · auto-deploy ke staging
│   ├── feat/M1-patient-intake  # feature branches per modul/sprint task
│   ├── feat/M4-soap-scribe
│   ├── feat/M9-audit-log
│   ├── fix/issue-NNN
│   └── chore/dep-bump
├── release/v0.1.0              # cut from develop · final QA · merge ke main + tag
└── hotfix/critical-NNN         # from main · merge to main + develop

4. 🔌 API & MCP Contracts

4a. REST API (Laravel apps)

Versioned · OpenAPI documented · Bearer token auth · rate-limited.

POST   /api/v1/auth/login                          # Sanctum token
POST   /api/v1/auth/logout
GET    /api/v1/me                                  # current user
# Patient PA (M1)
POST   /api/v1/patient/symptom/start               # start intake session
POST   /api/v1/patient/symptom/turn                # add user message · receive AI reply
GET    /api/v1/patient/symptom/{sessionId}         # current state
POST   /api/v1/patient/symptom/{sessionId}/escalate # human override
GET    /api/v1/patient/clinics/nearby              # M3 locator (lat/lng query)
POST   /api/v1/patient/appointments                # book appointment
# Doctor PA (M4)
GET    /api/v1/doctor/encounters                   # today's queue
GET    /api/v1/doctor/encounters/{id}              # encounter detail
POST   /api/v1/doctor/encounters                   # create new encounter
PATCH  /api/v1/doctor/encounters/{id}              # update SOAP fields
POST   /api/v1/doctor/encounters/{id}/scribe       # upload audio for SOAP
POST   /api/v1/doctor/encounters/{id}/orders       # create order set
POST   /api/v1/doctor/encounters/{id}/prescription # create RX
POST   /api/v1/doctor/encounters/{id}/sign-off     # complete encounter
# Pharmacy PA (M5)
GET    /api/v1/pharmacy/queue                      # ready/verifying/pending
POST   /api/v1/pharmacy/{rxId}/verify              # DDI + allergy check
POST   /api/v1/pharmacy/{rxId}/dispense            # mark dispensed
POST   /api/v1/pharmacy/{rxId}/print-label         # generate label PDF
# Admin PA (M7)
GET    /api/v1/admin/queue                         # registration queue
POST   /api/v1/admin/checkin/{patientId}
POST   /api/v1/admin/billing/{encId}/submit-claim  # MySalam/Socso/private
POST   /api/v1/admin/billing/{encId}/einvoice      # LHDN
# Audit (M9)
GET    /api/v1/audit/logs                          # query audit trail
GET    /api/v1/audit/logs/{id}                     # specific entry detail

4b. MCP Server (mcp-medix)

Standardised tool registry untuk agents. Setiap tool ada permission gate · audit · PII strip.

Tool Namespace                Tool Name              Description
─────────────────────────────────────────────────────────────────
clinical/                     cdss                   Clinical Decision Support
                              ddx                    Differential diagnosis
                              symptom_classifier     Triage colour
                              cpg_lookup             MOH CPG retrieve
medication/                   ddi_check              Drug-Drug Interaction
                              dose_calc              Dose-by-weight/eGFR
                              npra_stock             Drug DB lookup
                              halal_filter           Halal status check
                              generic_suggest        Generic substitution
patient/                      fhir_read              Patient FHIR resource
                              history_search         Vector similarity
                              vital_stream           Real-time vital
                              face_match             Biometric ID verify
imaging/                      dicom_query            Imaging worklist
                              report_template        Auto-draft report
billing/                      icd10_code             Auto-code from SOAP
                              einvoice_lhdn          LHDN submit
                              claim_filer            MySalam/Socso/private
                              panel_rate             Insurance rate sync
comms/                        waha_send              WhatsApp message
                              pager_api              On-call pager
                              sms_gw                 SMS via Twilio
scheduling/                   slot_find              Available slots
                              noshow_predict         No-show probability
                              resource_conflict      Room/staff conflict
admin/                        audit_write            Append audit log
                              perm_check             RBAC verify
                              feature_flag           Toggle check
                              consent_check          Patient consent verify

4c. MCP Tool Schema Example

{
  "name": "ddi_check",
  "description": "Check drug-drug interactions between proposed prescription and patient's current medication list.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "patient_id": { "type": "string", "format": "uuid" },
      "proposed_rx": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "drug_code": { "type": "string", "description": "NPRA code or RxNorm" },
            "dose_mg": { "type": "number" },
            "route": { "type": "string", "enum": ["po","iv","im","sc","topical"] }
          }
        }
      }
    },
    "required": ["patient_id", "proposed_rx"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "interactions": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "severity": { "enum": ["MINOR","MODERATE","MAJOR","CONTRAINDICATED"] },
            "description": { "type": "string" },
            "citation": { "type": "string", "description": "NPRA/Lexicomp/MOH CPG ref" },
            "suggested_alternative": { "type": "string" }
          }
        }
      },
      "passed": { "type": "boolean" }
    }
  },
  "permissions": ["patient:read", "medication:read"],
  "audit": true,
  "pii_strip": false
}

4d. Webhook Events (event bus)

patient.symptom.started        { patient_id, session_id, ts }
patient.symptom.completed      { patient_id, session_id, triage_color, summary }
patient.escalated              { patient_id, session_id, reason, severity }
appointment.booked             { appointment_id, patient_id, clinic_id, doctor_id, start_at }
encounter.created              { encounter_id, patient_id, doctor_id, clinic_id }
encounter.briefing_ready       { encounter_id, briefing_packet_url }
encounter.scribe_uploaded      { encounter_id, audio_url, duration_sec }
encounter.soap_drafted         { encounter_id, soap_id, draft_text }
encounter.signed_off           { encounter_id, doctor_id, completed_at }
prescription.created           { rx_id, encounter_id, drugs: [...] }
prescription.verified          { rx_id, pharmacist_id, ddi_passed }
prescription.dispensed         { rx_id, dispensed_at, label_url }
adverse.reaction.reported      { patient_id, rx_id, symptom, severity }
billing.claim.submitted        { encounter_id, claim_id, payer }
billing.einvoice.submitted     { encounter_id, einvoice_id }
audit.alert                    { rule, severity, details, ts }
guardrail.blocked              { agent, action, reason, escalated_to }

5. 🗄️ Database Schema

Doc Zam 11-section Patient Profile = canonical. Tables di MariaDB (clinical) + PostgreSQL (state · audit · vector).

5a. Patient (canonical 11-section · MariaDB)

5b. Related Tables (separate normalised)

5c. Indexing Strategy

• B-tree: patient.mrn, encounter.start_at, audit_log.ts
• Composite: (tenant_id, mrn), (patient_id, start_at)
• Vector: memory_vector.embedding (HNSW pgvector)
• Geo: clinics(lat, lng) via PostGIS or KD-tree
• Encryption: PII columns dgn AES-256 at rest · key dlm Vault

6. 🤖 Agent Specifications

Setiap PA = LangGraph state machine + tool set + memory tier + guardrail layer.

6a. Prompt Strategy (per agent)

System Prompt structure:
1. ROLE · "You are a [PA name] in MediEco hospital agentic eco-system."
2. SCOPE · "You ONLY handle [domain]. You DO NOT [excluded actions]."
3. CONSTRAINTS · "All medical suggestions MUST cite source from {NPRA, MOH CPG, hospital SOP}.
                  NEVER make a final clinical decision. Always defer to human clinician via HITL."
4. CONTEXT · {{patient_summary}} {{cpg_excerpts}} {{patient_history_top_5}}
5. TOOLS AVAILABLE · {{mcp_tool_list}}
6. OUTPUT FORMAT · Strict JSON dgn schema:
   { "action": "...", "rationale": "...", "citations": ["..."], "confidence": 0.85, "human_approval_needed": true }
7. SAFETY · "If anything looks like emergency (chest pain + dyspnea, stroke signs, etc.),
             output action='ESCALATE_999' immediately."

User Prompt:
{{user_message}}
{{conversation_history}}

7. 🎨 Frontend Architecture

Browser-first PWA · 4 role-based shells · zero-install.

7a. Design System

• Colour palette: based on Doc Zam mock (blue/teal primary · emerald/violet accents)
• Typography: SF Pro Text / Inter (UI) · JetBrains Mono (code/IDs)
• Component library: Tailwind UI patterns + Filament 3 components
• Icons: Heroicons + healthcare-specific custom set
• Accessibility: WCAG 2.1 AA · keyboard navigation · screen reader labels
• Mobile responsive: tested 320-768-1024-1440-1920px breakpoints

8. 🔄 DevOps Pipeline

8a. Environments

8b. CI Pipeline (.github/workflows/ci.yml)

on: [push, pull_request]
jobs:
  lint:
    - php-cs-fixer (PSR-12)
    - phpstan (level 8)
    - eslint + prettier
    - ruff (Python)
    - mypy (Python strict)
  test:
    - phpunit (Laravel · >75% coverage)
    - pytest (agents · >80% coverage)
    - playwright (E2E 3 patient scenarios)
    - schema migrations check (no breaking change)
  security:
    - composer audit
    - npm audit
    - pip-audit
    - trivy scan (Docker images)
    - secrets scan (gitleaks)
  build:
    - docker build (cached layers)
    - tag with sha + branch
    - push to ALESA registry

8c. CD Pipeline

Staging (auto · on develop merge):
  1. ansible-playbook deploy-staging.yml
  2. db:migrate (no-op if no new migrations)
  3. cache:clear
  4. opcache:reset (web request trigger per ALESA OLS pattern)
  5. smoke test (health endpoints · login · 1 patient flow)
  6. notify Slack/WhatsApp

Prod (manual · post-Q-gate):
  1. backup db (mariadb-dump + postgres pg_dump)
  2. backup current code (rsync to /home/alesa/backups/medieco-VYYYY.tgz)
  3. ansible-playbook deploy-prod.yml --check (dry run)
  4. operator approval prompt
  5. ansible-playbook deploy-prod.yml --apply
  6. db:migrate --force
  7. cache:clear · opcache:reset
  8. smoke test
  9. canary: 10% traffic to new build · monitor 15 min
  10. gradual cutover · or rollback if SLO breach

9. 👁️ Observability

10. 🔒 Security Model

11. 🧪 Testing Strategy

12. 📐 Coding Standards

• PHP: PSR-12 · php-cs-fixer auto-fix on commit · phpstan level 8
• Python: PEP 8 + ruff · type hints mandatory · mypy strict
• JS/TS: eslint + prettier · TypeScript strict
• SQL: Migrations only via Laravel/Alembic · NEVER manual ALTER on prod
• Naming: snake_case (DB · Python) · camelCase (PHP method) · PascalCase (Class)
• Comments: WHY not WHAT · only when non-obvious · no commented-out code in main
• Test naming: test_should_X_when_Y
• Commit messages: Conventional Commits (feat/fix/docs/test/chore/refactor)
• PR template: context · changes · test plan · screenshots · breaking changes
• Code review: 1 approval required (2 untuk security/clinical changes)
• No direct push to main/develop · feature branches mandatory
• No skip hooks (--no-verify) tanpa explicit approval

13. 🏃 Sprint Cadence