SilverGait - System Architecture

Six-node pipeline that scores raw health inputs, classifies frailty tier, and conditionally updates care plans. All nodes are deterministic - zero LLM calls.

Classification Rule

if cfs >= 7 or (katz <= 2 and sppb is not None and sppb <= 3):
    tier = "severely_frail"
elif cfs >= 5 or (katz <= 4 and sppb is not None and sppb <= 6):
    tier = "frail"
elif cfs >= 4 or (sppb is not None and sppb <= 9):
    tier = "pre_frail"
else:
    tier = "robust"

State Schema

class AssessmentState(TypedDict, total=False):
    user_id: str
    trigger: str              # onboarding | assessment | profile_update | biweekly_recheck
    language: str
    katz_answers: dict | None
    contributing: dict | None
    sppb_balance: int | None
    sppb_gait: int | None
    sppb_chair: int | None
    issues: list[str] | None
    katz_total: int | None
    cfs_score: int | None
    sppb_total: int | None
    frailty_tier: str | None
    risk_explanation: str | None
    previous_tier: str | None
    tier_changed: bool
    new_plans: list[dict]
    alerts: list[dict]
    health_snapshot_id: int | None
    assessment_id: int | None
    db: AsyncSession | None

Four-node pipeline triggered by each user chat message. Assembles full user context, invokes Gemini 2.5 Flash with native function calling, applies safety pattern matching, then persists.

Chat Tools - Gemini Function Calling

State Schema

class ChatState(TypedDict, total=False):
    user_id: str
    user_message: str
    language: str
    system_prompt: str | None
    user_context: UserContext | None
    agent_response: str | None
    tool_calls: list[dict] | None
    safety_alerts: list[dict]
    response_appendix: str | None
    db: AsyncSession | None

Core services that underpin both graphs. Zero LLM calls - all logic is rule-based or database-driven.

Six distinct phases, each mapped to specific graph triggers and LLM call counts.

Design philosophy: LLM only where reasoning is needed. Scoring, classification, routing, and plan selection are all deterministic.

SQLite via SQLAlchemy async (aiosqlite). Append-only design for full auditability.

Key Design Decisions

1. 1
   health_snapshots is append-only - never UPDATE, always INSERT. Enables diffs, trends, and full audit trail across sessions.
2. 2
   frailty_evaluations links its inputs - FK to both health_snapshot_id and assessment_id provides complete input traceability for each evaluation.
3. 3
   care_plans have lifecycle - status transitions from active → superseded, with superseded_by_id pointer to the replacement plan.
4. 4
   care_plans content is NOT LLM-generated - selected from content_library.py (expert-reviewed, curated content). LLM sub-agents personalize on top of these templates.
5. 5
   agent_runs tracks graph executions - graph_type, trigger, nodes executed, elapsed time. Essential for debugging and auditability.
6. 6
   alerts have source field - distinguishes assessment_graph vs chat_safety_gate vs system alerts for triage and display logic.

Every graph execution is event-driven. Each trigger maps to a specific API endpoint and graph.