gemstone-nexus · Phase 6

DOC13 — Diagrams

← Documents

Metadata

iddoc_idtitlecategorysource_pathsummarycontent_hashindexed_at
31DOC13DOC13 — Diagramsdoc_suiteDevResources/docs/DOC13-Diagrams.md``` Practitioner gemstone-api atlas-ollama (Whisper) gemstone-tts (Piper) |-- audio chunk -->| | | | |-- stream ---------->| | | |<-- partial transcript| | | |-- final transcript ->| (VAD end-of-turn) | | |-- query MCP Index B (Atlas context) ----------->| | |-- response t…2afc90475b51a3867d9fca96dd0ea717a2cdfcb22026-07-22 18:33:18

Content

# DOC13 — Diagrams

*Sequence and state diagrams*

**Initiative:** GemStone · **Version:** v2.0 (Rewrite) · **Status:** Approved for Build · **Date:** July 17, 2026

## 1. Voice Round-Trip Sequence

```
Practitioner        gemstone-api        atlas-ollama (Whisper)      gemstone-tts (Piper)
     |-- audio chunk -->|                     |                          |
     |                  |-- stream ---------->|                          |
     |                  |<-- partial transcript|                          |
     |                  |-- final transcript ->|  (VAD end-of-turn)       |
     |                  |-- query MCP Index B (Atlas context) ----------->|
     |                  |-- response text ------------------------------->|
     |                  |                     |     stream synthesize --->|
     |<-- audio chunk --|<--------------------------------------- audio --|
     |   (first chunk within 800ms of first response sentence)           |
```

## 2. Didymus Task Approval Flow

```
Any Worker/GemStone         Didymus Hub                 GemStone UI (universal surface)      Human
       |-- submit_task -------->|                              |                              |
       |                        |-- PENDING, visible ---------->|                              |
       |                        |                               |-- displayed, no source badge->|
       |                        |<-- approve_task --------------|<---------------------------- |
       |                        |-- APPROVED, approved_by/at set|                              |
       |<-- lease eligible -----|                               |                              |
       |-- execute, report ---->|-- COMPLETED/VERIFIED -------->|                              |
```

## 3. Security Tier Cascade

```
effective_tier = min(iq_tier, atlas_tier, gemstone_tier, practitioner_tier)

Example: IQ=Standard(1), Atlas=High Security(0), GemStone=Standard(1), Practitioner=Open Mode(2)
  -> effective_tier = min(1, 0, 1, 2) = 0 = High Security
  (Atlas being the most restrictive layer forces the whole session down, regardless
   of what the practitioner personally selected.)
Display names: High Security, Standard, Open Mode. Wire values: high_security, standard, open_mode.
```

## 4. Session Interruption and Resume

```
ACTIVE --[OS audio focus loss (incl. incoming call) / network drop / app backgrounding]--> snapshot written --> PAUSED
PAUSED --[session-ready chime fires]--> RESUMABLE
RESUMABLE --[one tap or app reopen]--> restore from Atlas Vault --> ACTIVE
(Identical path regardless of which of the three interruption causes triggered it.
 Extended Session timeout with confirmation ends the session; it is not an interruption cause.)
```

## 5. Co-dev Deploy Pipeline (Stage 2)

```
Windows co-dev                    GitHub                         T4 EC2 (dr)
     |-- edit / commit ------------>|                              |
     |-- git push (PAT local) ----->|                              |
     |-- plink: run-remote-docker-deploy.ps1 --------------------->|
     |                              |<-- git pull (PAT Basic, ephemeral)
     |                              |    docker compose up -d [--build]
     |                              |    nginx :80/:443 (compose)
     |                              |    supervisor: Stage 3 API image
     |<-- compose ps / health ------|                              |

DEVELOPMENT_DIRECTORY = /home/dr/AppDev/gemstone-nexus
Atomic concurrency: schema + API + Swagger + UI + tests + DOC12/DOC07/ledger in one change set.
```


---
NEXTECH Business Technology Management LLC · nex-tech.biz · (941) 499-5505