Code Map

A file-by-file guide to the codebase — where each module lives, what it does, how many lines it contains, and when you’d need to edit it.

Source Layout

src/
├── main.rs                          ← CLI entry point (~4,200 lines)
├── lib.rs                           ← Library re-exports (5 lines)
├── api/
│   ├── mod.rs                       ← pub mod anthropic; pub mod congress; pub mod openai;
│   ├── anthropic/
│   │   ├── mod.rs                   ← Re-exports
│   │   └── client.rs               ← Claude API client (~340 lines)
│   ├── congress/
│   │   ├── mod.rs                   ← Types and re-exports
│   │   ├── client.rs               ← Congress.gov HTTP client
│   │   └── bill.rs                 ← Bill listing, metadata, text versions
│   └── openai/
│       ├── mod.rs                   ← Re-exports
│       └── client.rs               ← Embeddings endpoint (~45 lines)
└── approp/
    ├── mod.rs                       ← pub mod for all submodules
    ├── ontology.rs                  ← All data types (~960 lines)
    ├── bill_meta.rs                 ← Bill metadata + classification (~1,280 lines)
    ├── extraction.rs                ← Extraction pipeline (~840 lines)
    ├── from_value.rs                ← Resilient JSON parsing (~690 lines)
    ├── xml.rs                       ← Congressional XML parser (~590 lines)
    ├── text_index.rs                ← Dollar amount indexing (~670 lines)
    ├── prompts.rs                   ← LLM system prompt (~310 lines)
    ├── verification.rs              ← Deterministic verification (~370 lines)
    ├── links.rs                     ← Cross-bill link persistence (~790 lines)
    ├── loading.rs                   ← Directory walking, bill loading (~340 lines)
    ├── query.rs                     ← Library API (~1,300 lines)
    ├── embeddings.rs                ← Embedding storage (~260 lines)
    ├── staleness.rs                 ← Hash chain checking incl bill_meta (~165 lines)
    └── progress.rs                  ← Extraction progress bar (~170 lines)

Supporting Files

tests/
└── cli_tests.rs                     ← 42 integration tests (~1,200 lines)

docs/
├── ARCHITECTURE.md                  ← Architecture doc (~416 lines)
└── FIELD_REFERENCE.md               ← JSON field reference (~348 lines)

book/
└── src/                             ← This mdbook documentation

data/
├── hr4366/                          ← FY2024 omnibus (2,364 provisions)
├── hr5860/                          ← FY2024 continuing resolution (130 provisions)
└── hr9468/                          ← VA supplemental (7 provisions)

File-by-File Reference

Core: CLI and Library Entry Points

Core: Data Types

Core: Extraction Pipeline

Core: Verification and Quality

Core: Query and Search

API Clients

Tests

In addition to integration tests, most modules contain inline unit tests in #[cfg(test)] mod tests { } blocks at the bottom of the file.

Data Flow Diagrams

How search --semantic flows through the code

main.rs: main()
  → match Commands::Search
  → handle_search()           [detects semantic.is_some()]
  → handle_semantic_search()  [async]
    → loading::load_bills()   [finds extraction.json files]
    → embeddings::load()      [for each bill directory]
    → OpenAIClient::embed()   [embeds query text — single API call, ~100ms]
    → for each provision:
        apply hard filters (type, division, dollars, etc.)
        cosine_similarity(query_vector, provision_vector)
    → sort by similarity descending
    → truncate to --top N
    → format output (table/json/jsonl/csv)

How extract flows through the code

main.rs: main()
  → match Commands::Extract
  → handle_extract()                     [async]
    → xml::parse_bill_xml()              [parse XML, get clean text + chunks]
    → ExtractionPipeline::new()
    → pipeline.extract_parallel()        [sends chunks to Claude in parallel]
      → for each chunk (bounded concurrency):
          AnthropicClient::create_message()
          from_value::parse_bill_extraction()
          save chunk artifacts to chunks/
    → merge provisions from all chunks
    → BillExtraction::compute_totals()   [sums provisions, never LLM arithmetic]
    → verification::verify_extraction()  [deterministic string matching]
    → write extraction.json, verification.json, metadata.json, tokens.json

How --similar flows through the code

main.rs: main()
  → match Commands::Search
  → handle_search()
  → handle_semantic_search()  [same entry point as --semantic]
    → loading::load_bills()
    → embeddings::load()      [for each bill]
    → look up source provision vector from stored vectors.bin  [NO API call]
    → cosine_similarity against all other provisions
    → sort, filter, truncate, format

Key Patterns to Follow

1. Library function first, CLI second

New logic goes in query.rs (or a new module). The CLI handler in main.rs calls the library function and formats output. Never put business logic in main.rs.

2. All query functions take &[LoadedBill] and return structs

No I/O, no formatting, no side effects in library code. All output structs derive Serialize for JSON output.

#![allow(unused)]
fn main() {
// Good:
pub fn my_query(bills: &[LoadedBill]) -> Vec<MyResult> { ... }

// Bad:
pub fn my_query(dir: &Path) -> Result<()> { ... }  // Does I/O
}

3. Serde for everything

All data types derive Serialize and Deserialize. This enables JSON, JSONL, and CSV output for free.

4. Tests in the same file

Unit tests go in #[cfg(test)] mod tests { } at the bottom of each module. Integration tests go in tests/cli_tests.rs.

5. Clippy clean with -D warnings

Clippy treats warnings as errors in CI. Fix all clippy suggestions at the root cause — don’t suppress with #[allow] unless absolutely necessary. Use #[allow(clippy::too_many_arguments)] sparingly.

6. Format with cargo fmt before committing

The CI rejects improperly formatted code.

Existing CLI Command Definitions

For reference when adding new commands, here are the existing command patterns in main.rs:

congress-approp download   --congress N --type T --number N --output-dir DIR [--enacted-only] [--format F] [--version V] [--dry-run]
congress-approp extract    --dir DIR [--parallel N] [--model M] [--dry-run]
congress-approp embed      --dir DIR [--model M] [--dimensions D] [--batch-size N] [--dry-run]
congress-approp search     --dir DIR [-t TYPE] [-a AGENCY] [--account A] [-k KW] [--bill B] [--division D] [--min-dollars N] [--max-dollars N] [--semantic Q] [--similar S] [--top N] [--format F] [--list-types]
congress-approp summary    --dir DIR [--format F] [--by-agency]
congress-approp compare    --base DIR --current DIR [-a AGENCY] [--format F]
congress-approp audit      --dir DIR [--verbose]
congress-approp upgrade    --dir DIR [--dry-run]
congress-approp api test
congress-approp api bill list --congress N [--type T] [--offset N] [--limit N] [--enacted-only]
congress-approp api bill get --congress N --type T --number N
congress-approp api bill text --congress N --type T --number N

Files That Don’t Exist Yet

These modules are designed but not implemented — they appear in the roadmap:

See NEXT_STEPS.md (gitignored) for detailed implementation plans.

Next Steps

• Adding a New Provision Type — the most common contributor task
• Adding a New CLI Command — how to add a new subcommand
• Testing Strategy — how the test suite works
• Architecture Overview — the big-picture design