# claimscout/va-claim-scout architecture

> Architecture diagram of the GitHub repository claimscout/va-claim-scout, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/claimscout/va-claim-scout
- Repository: https://github.com/claimscout/va-claim-scout

## Overview

1. **What this repository is**
   - This is not a software application with a backend or frontend.
   - It is a **prompt framework distribution repo**: the core “product” is written content that an external AI system loads and executes conversationally.
   - The repo’s architecture is therefore centered on **documentation, prompt assets, and versioned guidance**, not runtime code.

2. **Primary boundary: repo vs. AI platform**
   - The repository contains the framework artifacts.
   - The actual “runtime” is an **external AI chat platform** such as Claude, GPT-4o, Gemini, Copilot, or Grok.
   - All analysis, reasoning, and user interaction happen inside that external model; the repo itself does not process claims, store user data, or connect to VA systems.

3. **Core functional artifacts**
   - `VA_Claim_Scout_Pro.md` is the main high-capability prompt framework for deeper analysis.
   - `VA_Claim_Scout_Lite.md` is a reduced-context variant designed for lighter/free-tier AI platforms.
   - These are the two operational entry points and should be treated as the main “modules” in the system diagram.

4. **How the system is used**
   - A user either uploads or pastes one of the markdown files into an AI chat.
   - The AI reads the framework and responds to the trigger phrase **“Claim Scout, Help”** by presenting the menu/welcome flow.
   - From there, the conversation becomes an iterative analysis session where the AI helps the user reason through records, evidence, and claim strategy.

5. **Data flow**
   - Input source is entirely user-provided: medical records, service history, symptoms, letters, exam notes, and claim questions.
   - Those inputs flow into the AI chat session, where the prompt framework shapes the model’s analysis.
   - Output is conversational guidance: potential conditions, secondary/presumptive claim ideas, evidence gaps, exam prep, drafted statements, and messages to representatives.

6. **Main capability areas inside the framework**
   - The README makes clear the framework supports several analysis lanes:
     - identifying potentially compensable conditions,
     - surfacing secondary and presumptive claims,
     - evaluating evidence strength and gaps,
     - preparing for C&P exams and medical appointments,
     - drafting communications to a VSO, attorney, or VA representative,
     - producing buddy statements and impact statements.
   - These are the main logical subsystems to reflect in an architecture diagram, even though they are implemented as prompt behavior rather than code services.

7. **Important constraints and trust boundaries**
   - The framework explicitly does **not** file claims, access VA records, or replace legal counsel.
   - It is positioned as an analytical aid, not a legal-service provider.
   - A good architecture diagram should show a hard boundary between the AI-assisted reasoning layer and the actual VA filing/records systems.

8. **Pro vs. Lite architecture split**
   - **Pro** is intended for stronger models with larger context windows and deeper reasoning.
   - **Lite** is optimized for platforms with reduced context capacity and softer language.
   - This is a compatibility split, not a feature split: both versions share the same core mission, but Lite is adapted for lower-resource AI environments.

9. **Repository support files**
   - `README.md` is the main product overview and usage guide.
   - `CHANGELOG.md` provides version history and release notes.
   - `LICENSE.md` defines the open-source usage terms.
   - `VA Claim Scout – Quick Start Guide.pdf` and `VA_Claim_Scout.docx` are packaged onboarding/reference documents.
   - `.github/FUNDING.yml` is ancillary project-support metadata, not part of the claim-analysis workflow.

10. **External ecosystem and adjacent scope**
   - The README references a planned companion project, **SSDI Claim Scout**, which is conceptually separate but based on the same prompt-framework pattern.
   - It also references VA.gov for actual claim filing and notes that SSA representation is a different legal domain.
   - In an architecture diagram, these should appear as external systems the user may eventually interact with, but not as components inside this repository.

11. **What is notably absent**
   - There is no application server, database, API layer, authentication system, or build pipeline visible in the file tree.
   - The repo’s “logic” lives in authored markdown content, so its architecture is primarily **content distribution + external AI execution**.
   - That makes the repository lightweight and portable across AI platforms rather than tied to a single runtime stack.

Main entry points: [`README.md`](https://github.com/claimscout/va-claim-scout/blob/main/README.md) (README), [`VA_Claim_Scout_Pro.md`](https://github.com/claimscout/va-claim-scout/blob/main/VA_Claim_Scout_Pro.md) (Pro prompt), [`VA_Claim_Scout_Lite.md`](https://github.com/claimscout/va-claim-scout/blob/main/VA_Claim_Scout_Lite.md) (Lite prompt), [`LICENSE.md`](https://github.com/claimscout/va-claim-scout/blob/main/LICENSE.md) (License)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo_assets["Repository assets"]
  node_readme["README<br/>guide<br/>[README.md]"]
  node_pro_prompt["Pro prompt<br/>prompt framework"]
  node_lite_prompt["Lite prompt<br/>prompt framework"]
  node_quick_start["Quick start<br/>onboarding doc"]
  node_docx_guide["Docx guide<br/>reference doc"]
  node_changelog["Changelog<br/>release notes<br/>[CHANGELOG.md]"]
  node_license["License<br/>[LICENSE.md]"]
  node_funding["Funding<br/>metadata<br/>[FUNDING.yml]"]
end

subgraph group_ai_runtime["AI runtime"]
  node_chat_platform["AI chat<br/>external platform"]
  node_session{{"Claim Scout<br/>conversational workflow"}}
  node_analysis_lanes{{"Analysis lanes<br/>prompt logic"}}
  node_evidence_inputs[("User evidence<br/>source material")]
  node_guidance_outputs["Guidance output<br/>assistant output"]
end

subgraph group_va_ecosystem["VA ecosystem"]
  node_va_records[("VA records<br/>external system")]
  node_va_filing["VA.gov<br/>external filing system"]
  node_rep_support(("VSO / attorney<br/>human support"))
  node_ssdi_project["SSDI Scout<br/>adjacent project"]
end

node_user(("User<br/>person"))

node_user -->|"reviews"| node_readme
node_user -->|"loads"| node_pro_prompt
node_user -->|"loads"| node_lite_prompt
node_readme -->|"points to"| node_pro_prompt
node_readme -->|"points to"| node_lite_prompt
node_readme -->|"supports"| node_quick_start
node_readme -->|"supports"| node_docx_guide
node_readme -->|"documents"| node_changelog
node_pro_prompt -->|"executes on"| node_chat_platform
node_lite_prompt -->|"executes on"| node_chat_platform
node_chat_platform -->|"hosts"| node_session
node_session -->|"applies"| node_analysis_lanes
node_evidence_inputs -->|"feeds"| node_session
node_session -->|"produces"| node_guidance_outputs
node_guidance_outputs -->|"prepares"| node_rep_support
node_guidance_outputs -->|"informs"| node_va_filing
node_va_records -->|"may inform"| node_evidence_inputs
node_ssdi_project -.->|"patterned after"| node_chat_platform
node_license -.->|"governs"| node_funding

click node_readme "https://github.com/claimscout/va-claim-scout/blob/main/README.md"
click node_pro_prompt "https://github.com/claimscout/va-claim-scout/blob/main/VA_Claim_Scout_Pro.md"
click node_lite_prompt "https://github.com/claimscout/va-claim-scout/blob/main/VA_Claim_Scout_Lite.md"
click node_quick_start "https://github.com/claimscout/va-claim-scout/blob/main/VA Claim Scout – Quick Start Guide.pdf"
click node_docx_guide "https://github.com/claimscout/va-claim-scout/blob/main/VA_Claim_Scout.docx"
click node_changelog "https://github.com/claimscout/va-claim-scout/blob/main/CHANGELOG.md"
click node_license "https://github.com/claimscout/va-claim-scout/blob/main/LICENSE.md"
click node_funding "https://github.com/claimscout/va-claim-scout/blob/main/.github/FUNDING.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_pro_prompt,node_lite_prompt,node_quick_start,node_docx_guide,node_changelog,node_license,node_funding toneBlue
class node_chat_platform,node_session,node_analysis_lanes,node_evidence_inputs,node_guidance_outputs toneAmber
class node_va_records,node_va_filing,node_rep_support,node_ssdi_project toneMint
class node_user toneNeutral
```

## Components

### Repository assets

Versioned prompt content and supporting documentation shipped by this repo.

- [README](https://github.com/claimscout/va-claim-scout/blob/main/README.md): guide · Primary overview, usage flow, and product positioning. · `README.md`
- [Pro prompt](https://github.com/claimscout/va-claim-scout/blob/main/VA_Claim_Scout_Pro.md): prompt framework · Main high-capability analysis prompt for deeper reasoning. · `VA_Claim_Scout_Pro.md`
- [Lite prompt](https://github.com/claimscout/va-claim-scout/blob/main/VA_Claim_Scout_Lite.md): prompt framework · Reduced-context variant for smaller or lower-tier AI platforms. · `VA_Claim_Scout_Lite.md`
- [Quick start](https://github.com/claimscout/va-claim-scout/blob/HEAD/VA%20Claim%20Scout%20%E2%80%93%20Quick%20Start%20Guide.pdf): onboarding doc · Packaged reference guide for first-time use. · `VA Claim Scout – Quick Start Guide.pdf`
- [Docx guide](https://github.com/claimscout/va-claim-scout/blob/main/VA_Claim_Scout.docx): reference doc · Packaged editable/reference version of the framework guidance. · `VA_Claim_Scout.docx`
- [Changelog](https://github.com/claimscout/va-claim-scout/blob/main/CHANGELOG.md): release notes · Version history and release notes for the framework. · `CHANGELOG.md`
- [License](https://github.com/claimscout/va-claim-scout/blob/main/LICENSE.md): license · Open-source usage terms for the repository contents. · `LICENSE.md`
- [Funding](https://github.com/claimscout/va-claim-scout/blob/main/.github/FUNDING.yml): metadata · Ancillary project-support metadata, outside the claim workflow. · `.github/FUNDING.yml`

### AI runtime

External chat platform where the prompt framework is loaded and executed conversationally.

- **AI chat**: external platform · Claude, GPT-4o, Gemini, Copilot, Grok, or similar model runtime.
- **Claim Scout**: conversational workflow · The interactive analysis session started after loading the prompt and trigger phrase.
- **Analysis lanes**: prompt logic · Condition identification, secondary/presumptive ideas, evidence review, exam prep, drafting, and statements.
- **User evidence**: source material · Medical records, service history, symptoms, letters, exam notes, and claim questions supplied by the user.
- **Guidance output**: assistant output · Conversational recommendations, drafts, preparation notes, and evidence gap analysis.

### VA ecosystem

External systems and human actors adjacent to claim preparation and filing.

- **VA records**: external system · Official VA record systems; not accessed by the repo.
- **VA.gov**: external filing system · Actual claim filing destination and official VA process boundary.
- **VSO / attorney**: human support · Representative or counsel that the framework can help the user communicate with.
- **SSDI Scout**: adjacent project · Planned companion prompt-framework project in a separate domain.

### Other components

- **User**: person · Loads a prompt file and supplies claim-related material and questions.

## Connections

- User → README: reviews · User starts with the overview and usage guidance.
- User → Pro prompt: loads · User pastes or uploads the Pro framework into an AI chat.
- User → Lite prompt: loads · User pastes or uploads the Lite framework into an AI chat.
- README → Pro prompt: points to · README presents the main prompt entry point.
- README → Lite prompt: points to · README presents the lighter compatibility variant.
- README → Quick start: supports · Quick start provides onboarding for first use.
- README → Docx guide: supports · DOCX version offers packaged reference content.
- README → Changelog: documents · Changelog tracks releases and changes.
- Pro prompt → AI chat: executes on · Prompt behavior is realized inside the external model runtime.
- Lite prompt → AI chat: executes on · Lite variant also runs in the external model runtime.
- AI chat → Claim Scout: hosts · The platform hosts the interactive Claim Scout conversation.
- Claim Scout → Analysis lanes: applies · The prompt framework drives the analytical behaviors.
- User evidence → Claim Scout: feeds · User-provided records and questions are the input material.
- Claim Scout → Guidance output: produces · Outputs are conversational recommendations and drafts.
- Guidance output → VSO / attorney: prepares · User can turn outputs into messages or talking points for representatives.
- Guidance output → VA.gov: informs · Guidance may help the user prepare, but filing happens outside the repo.
- VA records → User evidence: may inform · Official records are an external source of truth the user may compare against.
- SSDI Scout → AI chat: patterned after · Referenced as a future companion using the same prompt-framework pattern.
- License → Funding: governs · Repository support metadata is ancillary and not part of the workflow.