# wayproyect/openbiin architecture

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

- Interactive diagram: https://gitdiagram.com/wayproyect/openbiin
- Repository: https://github.com/wayproyect/openbiin

## Overview

OpenBIIN is a BIN/IIN lookup product: users enter six or more digits in the web portal, the UI requests the public API, and the API looks up the matching issuer records in prefix-sharded CSV data. Six-digit searches can return multiple issuers; eight-digit searches use the recorded sub-ranges for greater precision. The web UI presents results responsively and includes an API reference. The source excerpts show the frontend-to-API and API-to-data paths; deployment routing is documented but not modeled as runtime code.

Main entry points: [`functions/index.js`](https://github.com/wayproyect/openbiin/blob/main/functions/index.js) (API handler), [`src/main.jsx`](https://github.com/wayproyect/openbiin/blob/main/src/main.jsx) (React bootstrap), [`src/components/BINSearch.jsx`](https://github.com/wayproyect/openbiin/blob/main/src/components/BINSearch.jsx) (BIN search), [`src/App.jsx`](https://github.com/wayproyect/openbiin/blob/main/src/App.jsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Lookup portal"]
  node_app_entry["React bootstrap<br/>[main.jsx]"]
  node_app_shell["App shell<br/>[App.jsx]"]
  node_search["BIN search<br/>[BINSearch.jsx]"]
  node_results["Result display<br/>[BINResult.jsx]"]
  node_theme["UI theme<br/>[theme.js]"]
end

subgraph group_service["Lookup API"]
  node_api["API handler<br/>[index.js]"]
  node_cache["Prefix cache<br/>[index.js]"]
  node_range_match["Range matching<br/>[index.js]"]
end

subgraph group_data["BIN records"]
  node_csv_store[("Sharded CSV data")]
end

node_visitor(("Portal visitor"))
node_api_client(("API consumer"))

node_visitor -->|"opens portal"| node_app_entry
node_api_client -->|"requests BIN"| node_api
node_app_entry -->|"renders"| node_app_shell
node_app_entry -->|"configures"| node_theme
node_app_shell -->|"renders"| node_search
node_search -->|"fetches BIN"| node_api
node_search -->|"renders results"| node_results
node_api -->|"loads prefix"| node_cache
node_api -->|"filters ranges"| node_range_match
node_api -->|"reads CSV"| node_csv_store

click node_app_entry "https://github.com/wayproyect/openbiin/blob/main/src/main.jsx"
click node_app_shell "https://github.com/wayproyect/openbiin/blob/main/src/App.jsx"
click node_search "https://github.com/wayproyect/openbiin/blob/main/src/components/BINSearch.jsx"
click node_results "https://github.com/wayproyect/openbiin/blob/main/src/components/BINResult.jsx"
click node_theme "https://github.com/wayproyect/openbiin/blob/main/src/theme/theme.js"
click node_api "https://github.com/wayproyect/openbiin/blob/main/functions/index.js"
click node_cache "https://github.com/wayproyect/openbiin/blob/main/functions/index.js"
click node_range_match "https://github.com/wayproyect/openbiin/blob/main/functions/index.js"
click node_csv_store "https://github.com/wayproyect/openbiin/tree/main/functions/data"

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_app_entry,node_app_shell,node_search,node_results,node_theme toneBlue
class node_api,node_cache,node_range_match toneAmber
class node_csv_store,node_api_client toneMint
class node_visitor toneIndigo
```

## Components

### Lookup portal

- [React bootstrap](https://github.com/wayproyect/openbiin/blob/main/src/main.jsx): `src/main.jsx`
- [App shell](https://github.com/wayproyect/openbiin/blob/main/src/App.jsx): `src/App.jsx`
- [BIN search](https://github.com/wayproyect/openbiin/blob/main/src/components/BINSearch.jsx): `src/components/BINSearch.jsx`
- [Result display](https://github.com/wayproyect/openbiin/blob/main/src/components/BINResult.jsx): `src/components/BINResult.jsx`
- [UI theme](https://github.com/wayproyect/openbiin/blob/main/src/theme/theme.js): `src/theme/theme.js`

### Lookup API

- [API handler](https://github.com/wayproyect/openbiin/blob/main/functions/index.js): `functions/index.js`
- [Prefix cache](https://github.com/wayproyect/openbiin/blob/main/functions/index.js): `functions/index.js`
- [Range matching](https://github.com/wayproyect/openbiin/blob/main/functions/index.js): `functions/index.js`

### BIN records

- [Sharded CSV data](https://github.com/wayproyect/openbiin/tree/main/functions/data): `functions/data`

### Other components

- **Portal visitor**
- **API consumer**

## Connections

- Portal visitor → React bootstrap: opens portal (evidence: `README.md`)
- API consumer → API handler: requests BIN (evidence: `README.md`)
- React bootstrap → App shell: renders (evidence: `src/main.jsx`)
- React bootstrap → UI theme: configures (evidence: `src/main.jsx`)
- App shell → BIN search: renders (evidence: `src/App.jsx`)
- BIN search → API handler: fetches BIN (evidence: `src/components/BINSearch.jsx`)
- BIN search → Result display: renders results (evidence: `src/components/BINSearch.jsx`)
- API handler → Prefix cache: loads prefix (evidence: `functions/index.js`)
- API handler → Range matching: filters ranges (evidence: `functions/index.js`)
- API handler → Sharded CSV data: reads CSV (evidence: `functions/index.js`)
