# smcronin/uspto-cli architecture

> Architecture diagram of the GitHub repository smcronin/uspto-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/smcronin/uspto-cli
- Repository: https://github.com/smcronin/uspto-cli

## Overview

This is a dual-domain USPTO CLI: users search patent or trademark records, then retrieve, analyze, export, or bundle results. Patent commands use the Open Data Portal (ODP); trademark discovery uses Trademark Search, while official case records and documents use TSDR. The graph preserves the README’s major documented command surfaces and separates the three service clients. Source excerpts are partial, so edges from command areas to clients rely on the SOURCE INDEX or README rather than a complete call trace.

Main entry points: [`internal/api/client.go`](https://github.com/smcronin/uspto-cli/blob/master/internal/api/client.go) (ODP API client), [`internal/tsdr/client.go`](https://github.com/smcronin/uspto-cli/blob/master/internal/tsdr/client.go) (TSDR client), [`cmd/root.go`](https://github.com/smcronin/uspto-cli/blob/master/cmd/root.go) (Command dispatcher), [`cmd/search.go`](https://github.com/smcronin/uspto-cli/blob/master/cmd/search.go) (Patent search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI entry and output"]
  node_cli["Command dispatcher<br/>[root.go]"]
  node_output["Structured output<br/>[output.go]"]
end

subgraph group_patents["Patent workflows"]
  node_patent_search["Patent search<br/>[search.go]"]
  node_application["Application records<br/>[app.go]"]
  node_patent_text["Patent text extraction<br/>[app_text.go]"]
  node_summary["Application summary<br/>[summary.go]"]
  node_family["Patent family<br/>[family.go]"]
  node_grants["Grant analysis<br/>[grant.go]"]
  node_ptab["PTAB proceedings<br/>[ptab.go]"]
  node_bulk["Bulk workflows<br/>[bulk.go]"]
  node_petitions["Petitions<br/>[petition.go]"]
  node_timeline["Prosecution timeline"]
end

subgraph group_trademarks["Trademark workflows"]
  node_tm_search["Mark discovery"]
  node_tm_case["Official case data<br/>[trademark_case.go]"]
  node_tm_docs["Case documents<br/>[trademark_docs.go]"]
  node_tm_ops["Trademark operations<br/>[trademark_ops.go]"]
  node_tm_decisions["Decisions and proceedings"]
end

subgraph group_services["API clients and data"]
  node_odp_client["ODP API client<br/>[client.go]"]
  node_tm_client["Trademark Search client<br/>[client.go]"]
  node_tsdr_client["TSDR client<br/>[client.go]"]
  node_types["Domain data types<br/>[types.go]"]
  node_text_extract["Document text extraction<br/>[extract.go]"]
end

node_user(("CLI user"))
node_odp(("USPTO Open Data Portal"))
node_tm_service(("Trademark Search service"))
node_tsdr(("USPTO TSDR"))

node_user -->|"runs commands"| node_cli
node_cli -.->|"routes commands"| node_patent_search
node_cli -.->|"routes commands"| node_tm_search
node_patent_search -->|"searches via"| node_odp_client
node_application -->|"retrieves records"| node_odp_client
node_patent_text -->|"fetches patent XML"| node_odp_client
node_patent_text -->|"extracts text"| node_text_extract
node_summary -->|"combines API data"| node_odp_client
node_family -->|"retrieves family data"| node_odp_client
node_grants -->|"fetches grant data"| node_odp_client
node_ptab -->|"retrieves proceedings"| node_odp_client
node_bulk -->|"retrieves bulk data"| node_odp_client
node_petitions -->|"retrieves petition data"| node_odp_client
node_timeline -->|"retrieves events"| node_odp_client
node_tm_search -->|"searches via"| node_tm_client
node_tm_case -->|"retrieves case data"| node_tsdr_client
node_tm_docs -->|"retrieves documents"| node_tsdr_client
node_tm_ops -->|"retrieves artifacts"| node_tsdr_client
node_tm_decisions -->|"searches decisions"| node_odp_client
node_odp_client -->|"requests ODP data"| node_odp
node_tm_client -->|"queries candidates"| node_tm_service
node_tsdr_client -->|"requests official records"| node_tsdr
node_patent_search -->|"uses data models"| node_types
node_application -->|"uses data models"| node_types
node_summary -->|"assembles summary"| node_types

click node_cli "https://github.com/smcronin/uspto-cli/blob/master/cmd/root.go"
click node_output "https://github.com/smcronin/uspto-cli/blob/master/cmd/output.go"
click node_patent_search "https://github.com/smcronin/uspto-cli/blob/master/cmd/search.go"
click node_application "https://github.com/smcronin/uspto-cli/blob/master/cmd/app.go"
click node_patent_text "https://github.com/smcronin/uspto-cli/blob/master/cmd/app_text.go"
click node_summary "https://github.com/smcronin/uspto-cli/blob/master/cmd/summary.go"
click node_family "https://github.com/smcronin/uspto-cli/blob/master/cmd/family.go"
click node_grants "https://github.com/smcronin/uspto-cli/blob/master/cmd/grant.go"
click node_ptab "https://github.com/smcronin/uspto-cli/blob/master/cmd/ptab.go"
click node_bulk "https://github.com/smcronin/uspto-cli/blob/master/cmd/bulk.go"
click node_petitions "https://github.com/smcronin/uspto-cli/blob/master/cmd/petition.go"
click node_timeline "https://github.com/smcronin/uspto-cli/blob/master/cmd/prosecution_timeline.go"
click node_tm_search "https://github.com/smcronin/uspto-cli/blob/master/cmd/trademark_search.go"
click node_tm_case "https://github.com/smcronin/uspto-cli/blob/master/cmd/trademark_case.go"
click node_tm_docs "https://github.com/smcronin/uspto-cli/blob/master/cmd/trademark_docs.go"
click node_tm_ops "https://github.com/smcronin/uspto-cli/blob/master/cmd/trademark_ops.go"
click node_tm_decisions "https://github.com/smcronin/uspto-cli/blob/master/cmd/trademark_decisions.go"
click node_odp_client "https://github.com/smcronin/uspto-cli/blob/master/internal/api/client.go"
click node_tm_client "https://github.com/smcronin/uspto-cli/blob/master/internal/tmsearch/client.go"
click node_tsdr_client "https://github.com/smcronin/uspto-cli/blob/master/internal/tsdr/client.go"
click node_types "https://github.com/smcronin/uspto-cli/blob/master/internal/types/types.go"
click node_text_extract "https://github.com/smcronin/uspto-cli/blob/master/internal/doctext/extract.go"

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_cli,node_output,node_user toneBlue
class node_patent_search,node_application,node_patent_text,node_summary,node_family,node_grants,node_ptab,node_bulk,node_petitions,node_timeline toneAmber
class node_tm_search,node_tm_case,node_tm_docs,node_tm_ops,node_tm_decisions toneMint
class node_odp_client,node_tm_client,node_tsdr_client,node_types,node_text_extract toneRose
class node_odp,node_tm_service,node_tsdr toneIndigo
```

## Components

### CLI entry and output

- [Command dispatcher](https://github.com/smcronin/uspto-cli/blob/master/cmd/root.go): `cmd/root.go`
- [Structured output](https://github.com/smcronin/uspto-cli/blob/master/cmd/output.go): `cmd/output.go`

### Patent workflows

- [Patent search](https://github.com/smcronin/uspto-cli/blob/master/cmd/search.go): `cmd/search.go`
- [Application records](https://github.com/smcronin/uspto-cli/blob/master/cmd/app.go): `cmd/app.go`
- [Patent text extraction](https://github.com/smcronin/uspto-cli/blob/master/cmd/app_text.go): `cmd/app_text.go`
- [Application summary](https://github.com/smcronin/uspto-cli/blob/master/cmd/summary.go): `cmd/summary.go`
- [Patent family](https://github.com/smcronin/uspto-cli/blob/master/cmd/family.go): `cmd/family.go`
- [Grant analysis](https://github.com/smcronin/uspto-cli/blob/master/cmd/grant.go): `cmd/grant.go`
- [PTAB proceedings](https://github.com/smcronin/uspto-cli/blob/master/cmd/ptab.go): `cmd/ptab.go`
- [Bulk workflows](https://github.com/smcronin/uspto-cli/blob/master/cmd/bulk.go): `cmd/bulk.go`
- [Petitions](https://github.com/smcronin/uspto-cli/blob/master/cmd/petition.go): `cmd/petition.go`
- [Prosecution timeline](https://github.com/smcronin/uspto-cli/blob/master/cmd/prosecution_timeline.go): `cmd/prosecution_timeline.go`

### Trademark workflows

- [Mark discovery](https://github.com/smcronin/uspto-cli/blob/master/cmd/trademark_search.go): `cmd/trademark_search.go`
- [Official case data](https://github.com/smcronin/uspto-cli/blob/master/cmd/trademark_case.go): `cmd/trademark_case.go`
- [Case documents](https://github.com/smcronin/uspto-cli/blob/master/cmd/trademark_docs.go): `cmd/trademark_docs.go`
- [Trademark operations](https://github.com/smcronin/uspto-cli/blob/master/cmd/trademark_ops.go): `cmd/trademark_ops.go`
- [Decisions and proceedings](https://github.com/smcronin/uspto-cli/blob/master/cmd/trademark_decisions.go): `cmd/trademark_decisions.go`

### API clients and data

- [ODP API client](https://github.com/smcronin/uspto-cli/blob/master/internal/api/client.go): `internal/api/client.go`
- [Trademark Search client](https://github.com/smcronin/uspto-cli/blob/master/internal/tmsearch/client.go): `internal/tmsearch/client.go`
- [TSDR client](https://github.com/smcronin/uspto-cli/blob/master/internal/tsdr/client.go): `internal/tsdr/client.go`
- [Domain data types](https://github.com/smcronin/uspto-cli/blob/master/internal/types/types.go): `internal/types/types.go`
- [Document text extraction](https://github.com/smcronin/uspto-cli/blob/master/internal/doctext/extract.go): `internal/doctext/extract.go`

### Other components

- **CLI user**
- **USPTO Open Data Portal**
- **Trademark Search service**
- **USPTO TSDR**

## Connections

- CLI user → Command dispatcher: runs commands
- Command dispatcher → Patent search: routes commands
- Command dispatcher → Mark discovery: routes commands
- Patent search → ODP API client: searches via (evidence: `cmd/search.go`)
- Application records → ODP API client: retrieves records (evidence: `cmd/app.go`)
- Patent text extraction → ODP API client: fetches patent XML (evidence: `cmd/app_text.go`)
- Patent text extraction → Document text extraction: extracts text (evidence: `cmd/app_text.go`)
- Application summary → ODP API client: combines API data (evidence: `cmd/summary.go`)
- Patent family → ODP API client: retrieves family data (evidence: `cmd/family.go`)
- Grant analysis → ODP API client: fetches grant data (evidence: `cmd/grant.go`)
- PTAB proceedings → ODP API client: retrieves proceedings (evidence: `cmd/ptab.go`)
- Bulk workflows → ODP API client: retrieves bulk data (evidence: `cmd/bulk.go`)
- Petitions → ODP API client: retrieves petition data (evidence: `cmd/petition.go`)
- Prosecution timeline → ODP API client: retrieves events (evidence: `cmd/prosecution_timeline.go`)
- Mark discovery → Trademark Search client: searches via (evidence: `cmd/trademark_search.go`)
- Official case data → TSDR client: retrieves case data (evidence: `cmd/trademark_case.go`)
- Case documents → TSDR client: retrieves documents (evidence: `cmd/trademark_docs.go`)
- Trademark operations → TSDR client: retrieves artifacts (evidence: `cmd/trademark_ops.go`)
- Decisions and proceedings → ODP API client: searches decisions (evidence: `cmd/trademark_decisions.go`)
- ODP API client → USPTO Open Data Portal: requests ODP data (evidence: `README.md`)
- Trademark Search client → Trademark Search service: queries candidates (evidence: `README.md`)
- TSDR client → USPTO TSDR: requests official records (evidence: `README.md`)
- Patent search → Domain data types: uses data models (evidence: `cmd/search.go`)
- Application records → Domain data types: uses data models (evidence: `cmd/app.go`)
- Application summary → Domain data types: assembles summary (evidence: `cmd/summary.go`)
