# usgpo/bulk-data architecture

> Architecture diagram of the GitHub repository usgpo/bulk-data, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/usgpo/bulk-data
- Repository: https://github.com/usgpo/bulk-data

## Overview

##### Project type and purpose
- This is a **documentation repository** for the Government Publishing Office’s (GPO) bulk‐data service (“govinfo bulk data”). It contains Markdown user guides (and corresponding PDFs) explaining how to download and use XML/JSON endpoints for collections like BILLS, CFR, FR, ECFR, etc.
- It is _not_ a runtime application or microservice codebase, but rather a set of static assets (guides and sample XML files) supporting an external API service.

##### File structure
- Top‐level files: Markdown user guides (e.g., `Bills-XML-User-Guide.md`, `CFR-XML_User-Guide.md`, etc.), a README, and a CODEOWNERS file.
- `pdf/`: prebuilt PDF versions of each guide.
- `ndash-changes-March2024/`: sample XML snapshots (“current” vs. “updated”) for ECFR and FR titles used as examples in the guides.
- No source code, build scripts, or backend code—pure documentation and sample data.

##### README for additional insights
- Explains the purpose: link to govinfo bulkdata portal, how to fetch XML/JSON, sample URLs, and usage notes (e.g., Accept headers).

##### Main components
a. **External System**:
- _GPO govinfo Bulkdata Service_ (the actual API endpoint host that serves XML or JSON for each collection).
- Collections: BILLS, CFR, FR, ECFR, etc.
b. **Documentation Repository** (this project):
- Markdown User Guides—hosted on GitHub.
- PDF folder with rendered user guides.
- Sample XML snapshot folders under `ndash-changes-March2024`.
c. **Consumers/Users**:
- CLI tools, scripts, or manual curl/browser requests to the bulkdata endpoints guided by the docs.

##### Relationships and data flows
- **Users** consult the **User Guides** in the **Documentation Repo** (locally or via GitHub/GitHub Pages).
- Users send HTTP requests to the external service, receiving structured data.
- Sample XML in `ndash-changes-March2024` demonstrates “diff” use cases (current vs. updated).

##### Architectural patterns and design principles
- **Static content distribution**: the docs are a static site (Markdown + PDFs), versioned in Git.
- **Separation of concerns**: documentation (this repo) vs. runtime service (govinfo API).
- **Extensibility**: adding new guides or sample data maps to new collections/endpoints.

##### Checklist
- [ ] All three zones clearly labeled (Docs, API, Users)
- [ ] Each folder or functional group shown as a component
- [ ] Notes indicating “Accept: application/json” header requirement and both XML/JSON support

## Diagram (Mermaid)

```mermaid
flowchart LR
    %% Documentation Zone
    subgraph "Documentation Zone"
        direction TB
        README["README.md"]:::doc
        CODEOWNERS["CODEOWNERS"]:::doc
        subgraph "Markdown User Guides"
            direction TB
            BILLSGuide["Bills-XML-User-Guide.md"]:::doc
            BILLSSummaryGuide["Bills-Summary-XML-User-Guide.md"]:::doc
            CFRGuide["CFR-XML_User-Guide.md"]:::doc
            ECFRGuide["ECFR-XML-User-Guide.md"]:::doc
            FRGuide["FR-XML_User-Guide.md"]:::doc
        end
        subgraph "PDF Guides"
            direction TB
            pdfBILLS["BILLS-XML_User-Guide-v2.pdf"]:::doc
            pdfBILLSUM["BILLSUM-XML_User-Guide-v2.pdf"]:::doc
            pdfCFR["CFR-XML_User-Guide-v1.pdf"]:::doc
            pdfFR["FR-XML_User-Guide-v1.pdf"]:::doc
        end
        subgraph "Sample XML Snapshots"
            direction TB
            subgraph "Current Snapshots"
                direction TB
                curECFR1["ECFR-title1.xml"]:::doc
                curECFR14["ECFR-title14.xml"]:::doc
                curECFR15["ECFR-title15.xml"]:::doc
                curFR["FR-2024-02-12.xml"]:::doc
            end
            subgraph "Updated Snapshots"
                direction TB
                updECFR1["ECFR-title1.xml"]:::doc
                updECFR14["ECFR-title14.xml"]:::doc
                updECFR15["ECFR-title15.xml"]:::doc
                updFR["FR-2024-02-12.xml"]:::doc
            end
        end
    end

    %% Service Zone
    subgraph "Service Zone"
        direction TB
        API["GPO govinfo Bulkdata API"]:::api
        BillsEndpoint["/bulkdata/xml/BILLS/{congress}/{chamber}/{doc}"]:::api
        JSONEndpoint["/bulkdata/json/{collection}/{year}/{id}"]:::api
        FREndpoint["/bulkdata/FR/{year}/{month}/{day}"]:::api
    end

    %% User Zone
    subgraph "User Zone"
        direction TB
        User["Users (CLI, scripts, browser)"]:::user
    end

    %% Connections
    User -->|"Read guides, download PDFs"| README
    README -->|"Guidance on endpoints"| API
    User -->|"GET /bulkdata/... → 200 OK"| API
    API -->|"Returns XML/JSON payload"| User
    BILLSGuide -->|Uses samples| curECFR1
    ECFRGuide -->|Diff examples| updECFR1

    %% Click Events
    click README "https://github.com/usgpo/bulk-data/blob/main/README.md"
    click CODEOWNERS "https://github.com/usgpo/bulk-data/tree/main/CODEOWNERS"
    click BILLSGuide "https://github.com/usgpo/bulk-data/blob/main/Bills-XML-User-Guide.md"
    click BILLSSummaryGuide "https://github.com/usgpo/bulk-data/blob/main/Bills-Summary-XML-User-Guide.md"
    click CFRGuide "https://github.com/usgpo/bulk-data/blob/main/CFR-XML_User-Guide.md"
    click ECFRGuide "https://github.com/usgpo/bulk-data/blob/main/ECFR-XML-User-Guide.md"
    click FRGuide "https://github.com/usgpo/bulk-data/blob/main/FR-XML_User-Guide.md"
    click pdfBILLS "https://github.com/usgpo/bulk-data/blob/main/pdf/BILLS-XML_User-Guide-v2.pdf"
    click pdfBILLSUM "https://github.com/usgpo/bulk-data/blob/main/pdf/BILLSUM-XML_User-Guide-v2.pdf"
    click pdfCFR "https://github.com/usgpo/bulk-data/blob/main/pdf/CFR-XML_User-Guide-v1.pdf"
    click pdfFR "https://github.com/usgpo/bulk-data/blob/main/pdf/FR-XML_User-Guide-v1.pdf"
    click curECFR1 "https://github.com/usgpo/bulk-data/blob/main/ndash-changes-March2024/current/ECFR-title1.xml"
    click curECFR14 "https://github.com/usgpo/bulk-data/blob/main/ndash-changes-March2024/current/ECFR-title14.xml"
    click curECFR15 "https://github.com/usgpo/bulk-data/blob/main/ndash-changes-March2024/current/ECFR-title15.xml"
    click curFR "https://github.com/usgpo/bulk-data/blob/main/ndash-changes-March2024/current/FR-2024-02-12.xml"
    click updECFR1 "https://github.com/usgpo/bulk-data/blob/main/ndash-changes-March2024/updated/ECFR-title1.xml"
    click updECFR14 "https://github.com/usgpo/bulk-data/blob/main/ndash-changes-March2024/updated/ECFR-title14.xml"
    click updECFR15 "https://github.com/usgpo/bulk-data/blob/main/ndash-changes-March2024/updated/ECFR-title15.xml"
    click updFR "https://github.com/usgpo/bulk-data/blob/main/ndash-changes-March2024/updated/FR-2024-02-12.xml"

    %% Styles
    classDef doc fill:#D0E6FF,stroke:#004E9F
    classDef api fill:#D0FFD0,stroke:#009F00
    classDef user fill:#FFE4C4,stroke:#CC6600
```
