# cmharlow/lc-reconcile architecture

> Architecture diagram of the GitHub repository cmharlow/lc-reconcile, 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/cmharlow/lc-reconcile
- Repository: https://github.com/cmharlow/lc-reconcile

## Overview

##### Project Type & Purpose
- This is an open-source, Python-based HTTP reconciliation service (a microservice) that speaks the OpenRefine Reconciliation API.
- It sits between the OpenRefine UI (the client) and the Library of Congress APIs (id.loc.gov), enriching OpenRefine with fuzzy and alternate‐label matching for LCNAF and LCSH.

##### File Structure & Architectural Hints
- Top-level files:
– reconcile.py: main Flask (or similar) HTTP server handling API requests.
– text.py: normalization library for cleaning and canonicalizing query strings.
– requirements.txt: indicates Flask, requests, fuzzywuzzy, etc.
– README.md: details the reconciliation logic (Suggest + DidYouMean + ranking via fuzzywuzzy).
- No database, no frontend code—this is a thin, stateless HTTP service.

##### Key Components
a. OpenRefine Client
– Represents the user’s browser instance running the OpenRefine UI.
– Initiates reconciliation via HTTP calls.
b. Reconciliation Service (Your Code)
– HTTP Server Layer (Flask app in reconcile.py)
- Exposes endpoints: root for metadata, POST /reconcile or GET /reconcile queries (per the API spec).
– Business Logic Layer
- Query Normalizer (text.py)
- Suggest & DidYouMean orchestrator (invokes id.loc.gov endpoints)
- Ranking Module (fuzzywuzzy scoring and top-3 selection)
– Response Formatter
- Builds JSON result conforming to OpenRefine spec.
c. External Services
– id.loc.gov Suggest API
– id.loc.gov DidYouMean API
d. (Optional) Monitoring/Debug
– Debug flag in reconcile.py; logs printed to console.

##### Architectural Patterns & Design Principles
- Layered decomposition:
– API Layer (Flask)
– Service Layer (normalization + orchestration)
– Integration Layer (external HTTP clients)
- Single Responsibility: text.py only normalizes text; reconcile.py orchestrates heavy lifting.
- Statelessness: no persisted state or DB; each request is independent.

##### Technologies & Libraries
- Python 3.7+
- Flask (or Bottle) for HTTP server
- requests for external HTTP calls
- fuzzywuzzy for string matching/ranking
- text.py: custom normalizer for LC peculiarities

##### What to Include on the Canvas
- Title: “Library of Congress Reconciliation Service – Architecture”
– Client Layer
– Service Layer
– External API Layer
- All endpoints and modules with clear names (e.g., ReconService, TextNormalizer)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Client["OpenRefine Client"]:::client
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        HTTP["HTTP Server\n(reconcile.py)"]:::service
        Normalizer["Text Normalizer\n(text.py)"]:::service
        Orchestrator["Suggest & DidYouMean Orchestrator"]:::service
        Ranking["Ranking Module\n(fuzzywuzzy)"]:::service
        Formatter["Response Formatter"]:::service
        Debug["Debug Logger Flag"]:::service
    end

    %% Project Artifacts
    subgraph "Project Artifacts"
        direction TB
        Req["requirements.txt"]:::docs
        Readme["README.md"]:::docs
    end

    %% External API Layer
    subgraph "External API Layer"
        direction TB
        SuggestAPI["LC Suggest API"]:::external
        DidYouMeanAPI["LC DidYouMean API"]:::external
    end

    %% Flows
    Client -->|"User query request"| HTTP
    HTTP -->|"normalize(query)"| Normalizer
    HTTP -->|"GET /suggest?q=..."| SuggestAPI
    HTTP -->|"GET /didyoumean?label=..."| DidYouMeanAPI
    HTTP -->|"score & sort"| Ranking
    HTTP -->|"format JSON"| Formatter
    Formatter -->|"JSON top 3 candidates"| Client
    HTTP --- Debug

    %% Click Events
    click HTTP "https://github.com/cmharlow/lc-reconcile/blob/master/reconcile.py"
    click Normalizer "https://github.com/cmharlow/lc-reconcile/blob/master/text.py"
    click Req "https://github.com/cmharlow/lc-reconcile/blob/master/requirements.txt"
    click Readme "https://github.com/cmharlow/lc-reconcile/blob/master/README.md"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef service fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
    classDef docs fill:#E0E0E0,stroke:#000,stroke-width:1px
```
