# adrianestebanvelascoobando956-del/blockchain architecture

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

- Interactive diagram: https://gitdiagram.com/adrianestebanvelascoobando956-del/blockchain
- Repository: https://github.com/adrianestebanvelascoobando956-del/blockchain

## Overview

1. **Project shape**
   - This is a **single-page, client-side application** with no backend service.
   - The entire system runs in the browser from `index.html`, with presentation in `style.css` and logic split across `js/`.

2. **Top-level architectural boundary**
   - The main boundary is between the **UI layer** and the **domain logic**.
   - UI renders forms, tables, status indicators, and QR-related views.
   - Domain logic owns the cattle ledger, block creation, validation, and role-based behavior.

3. **Core domain: a local blockchain ledger**
   - The central subsystem is a **blockchain-like chain of immutable records** for cattle traceability.
   - Each block stores index, timestamp, transaction type, data payload, emitting role, previous hash, and current hash.
   - Integrity depends on chained SHA-256 hashing, so any historical edit invalidates later blocks.

4. **Role-based workflow**
   - The app models three operational roles:
     - **Originador (Rol 1)**: creates bovine registration records.
     - **Agregador (Rol 2)**: appends sanitary/vaccination events.
     - **Verificador (Rol 3)**: inspects the chain, validates hashes, and supports audit-style verification.
   - Role selection is a functional access boundary: it changes which actions and views are available, but everything still executes locally in the browser.

5. **JavaScript module responsibilities**
   - `js/blockchain.js` is the core ledger engine: block structure, hash generation, chain linking, and validation checks.
   - `js/roles.js` likely centralizes role definitions and permissions or role-specific UI logic.
   - `js/ui.js` handles rendering, user interaction, and updating the visible state.
   - `js/app.js` is the bootstrap/orchestration layer that wires the modules together on page load.

6. **Persistence model**
   - State is stored in **browser `localStorage`**, not in a database or remote API.
   - That includes the blockchain history and session-related state, which makes the app self-contained and offline-capable.
   - Persistence is therefore tied to the browser profile/device, not shared across users.

7. **Verification and integrity flow**
   - When a new record is created, the app hashes the block content plus the previous block hash.
   - When validating, it recomputes the chain from the genesis block forward and compares stored hashes.
   - The verifier role is designed to surface corruption immediately, including the “cadena inválida” state described in the README.

8. **Audit/inspection output**
   - The app presents the chain as a **linear traceability history** rather than a distributed network view.
   - That makes the visible model closer to a ledger inspector than a peer-to-peer blockchain node.
   - QR generation is part of the audit boundary: it turns verified traceability data into a scannable artifact for physical inspection.

9. **External dependencies**
   - The app relies on **CryptoJS** for SHA-256 hashing.
   - It relies on **QRCode.js** for QR code generation.
   - These are frontend libraries loaded into the browser, so they affect the architecture only as client-side capabilities, not services.

10. **Presentation layer**
   - `style.css` provides a modern responsive UI with card-based layouts and CSS variables.
   - There is no indication of a component framework; the interface is built with vanilla HTML/CSS/JS.

11. **Runtime and deployment model**
   - The app is meant to run as a **static website**.
   - It can be opened directly from disk or served with a simple static server like `serve` or `http-server`.
   - There is no build pipeline, API server, auth service, or cloud dependency in the repo structure.

12. **What an architecture diagram should emphasize**
   - Draw the app as a **browser-hosted system** with these major parts:
     - Static shell (`index.html`, `style.css`)
     - UI/controller layer (`js/ui.js`, `js/app.js`)
     - Role/permission layer (`js/roles.js`)
     - Blockchain/ledger engine (`js/blockchain.js`)
     - Browser storage (`localStorage`)
     - Client-side crypto and QR libraries
   - The key data flow is: **user action → role check/UI event → block creation or validation → hash computation → local persistence → UI refresh**.

Main entry points: [`js/blockchain.js`](https://github.com/adrianestebanvelascoobando956-del/blockchain/blob/main/js/blockchain.js) (blockchain.js), [`js/ui.js`](https://github.com/adrianestebanvelascoobando956-del/blockchain/blob/main/js/ui.js) (ui.js), [`js/app.js`](https://github.com/adrianestebanvelascoobando956-del/blockchain/blob/main/js/app.js) (app.js), [`index.html`](https://github.com/adrianestebanvelascoobando956-del/blockchain/blob/main/index.html) (index.html)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_shell["Static shell"]
  node_n_index["index.html<br/>entry document<br/>[index.html]"]
  node_n_style["style.css<br/>ui stylesheet<br/>[style.css]"]
end

subgraph group_grp_ui["UI layer"]
  node_n_ui["ui.js<br/>ui controller<br/>[ui.js]"]
  node_n_qr_view["QR output<br/>audit artifact"]
end

subgraph group_grp_domain["Domain logic"]
  node_n_app["app.js<br/>bootstrap<br/>[app.js]"]
  node_n_roles["roles.js<br/>role policy<br/>[roles.js]"]
  node_n_chain["blockchain.js<br/>ledger engine<br/>[blockchain.js]"]
  node_n_origin(("Originador<br/>role 1"))
  node_n_agg(("Agregador<br/>role 2"))
  node_n_verif(("Verificador<br/>role 3"))
  node_n_ledger[("Cattle ledger<br/>traceability chain")]
  node_n_block["Block record<br/>chain entry"]
  node_n_validate{{"Validation<br/>integrity check"}}
end

subgraph group_grp_platform["Browser platform"]
  node_n_local[("localStorage<br/>browser storage")]
  node_n_crypto{{"CryptoJS<br/>sha256 library"}}
  node_n_qr{{"QRCode.js<br/>qr library"}}
end

node_n_index -->|"loads"| node_n_ui
node_n_index -->|"boots"| node_n_app
node_n_style -->|"styles"| node_n_ui
node_n_app -->|"wires"| node_n_roles
node_n_app -->|"wires"| node_n_chain
node_n_app -->|"wires"| node_n_ui
node_n_ui -->|"checks"| node_n_roles
node_n_ui -->|"invokes"| node_n_chain
node_n_chain -->|"hashes"| node_n_crypto
node_n_chain -->|"persists"| node_n_local
node_n_chain -->|"manages"| node_n_ledger
node_n_ledger -->|"contains"| node_n_block
node_n_verif -->|"drives"| node_n_validate
node_n_validate -->|"recomputes"| node_n_chain
node_n_origin -->|"creates"| node_n_chain
node_n_agg -->|"appends"| node_n_chain
node_n_verif -->|"inspects"| node_n_chain
node_n_ui -->|"renders"| node_n_qr_view
node_n_qr_view -->|"generates"| node_n_qr

click node_n_index "https://github.com/adrianestebanvelascoobando956-del/blockchain/blob/main/index.html"
click node_n_style "https://github.com/adrianestebanvelascoobando956-del/blockchain/blob/main/style.css"
click node_n_app "https://github.com/adrianestebanvelascoobando956-del/blockchain/blob/main/js/app.js"
click node_n_ui "https://github.com/adrianestebanvelascoobando956-del/blockchain/blob/main/js/ui.js"
click node_n_roles "https://github.com/adrianestebanvelascoobando956-del/blockchain/blob/main/js/roles.js"
click node_n_chain "https://github.com/adrianestebanvelascoobando956-del/blockchain/blob/main/js/blockchain.js"

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_n_index,node_n_style toneBlue
class node_n_ui,node_n_qr_view toneAmber
class node_n_app,node_n_roles,node_n_chain,node_n_origin,node_n_agg,node_n_verif,node_n_ledger,node_n_block,node_n_validate toneMint
class node_n_local,node_n_crypto,node_n_qr toneRose
```

## Components

### Static shell

Browser entrypoint and presentation assets.

- [index.html](https://github.com/adrianestebanvelascoobando956-del/blockchain/blob/main/index.html): entry document · Static browser entrypoint that loads the app. · `index.html`
- [style.css](https://github.com/adrianestebanvelascoobando956-del/blockchain/blob/main/style.css): ui stylesheet · Responsive visual styling for the single-page interface. · `style.css`

### UI layer

Rendering and interaction handling in the browser.

- [ui.js](https://github.com/adrianestebanvelascoobando956-del/blockchain/blob/main/js/ui.js): ui controller · Renders forms, tables, status, and QR views; handles user interaction. · `js/ui.js`
- **QR output**: audit artifact · Rendered traceability code for inspection and sharing.

### Domain logic

Ledger, roles, and application orchestration.

- [app.js](https://github.com/adrianestebanvelascoobando956-del/blockchain/blob/main/js/app.js): bootstrap · Wires modules together and starts the app. · `js/app.js`
- [roles.js](https://github.com/adrianestebanvelascoobando956-del/blockchain/blob/main/js/roles.js): role policy · Defines role behavior and access boundaries for the workflow. · `js/roles.js`
- [blockchain.js](https://github.com/adrianestebanvelascoobando956-del/blockchain/blob/main/js/blockchain.js): ledger engine · Creates blocks, chains hashes, and validates integrity. · `js/blockchain.js`
- **Originador**: role 1 · Creates bovine registration records.
- **Agregador**: role 2 · Appends sanitary and vaccination events.
- **Verificador**: role 3 · Inspects the chain and validates hashes for audit.
- **Cattle ledger**: traceability chain · Linear history of immutable cattle records stored as chained blocks.
- **Block record**: chain entry · Single immutable record with index, timestamp, payload, role, and hashes.
- **Validation**: integrity check · Recomputes the chain from genesis and flags invalid hashes.

### Browser platform

Client-side persistence and library capabilities.

- **localStorage**: browser storage · Persists ledger history and session state in the browser profile.
- **CryptoJS**: sha256 library · Client-side hashing used to compute block digests.
- **QRCode.js**: qr library · Generates scannable QR artifacts for traceability inspection.

## Connections

- index.html → ui.js: loads · The static document hosts the interactive UI.
- index.html → app.js: boots · Page load starts the application bootstrap.
- style.css → ui.js: styles · CSS shapes the rendered interface.
- app.js → roles.js: wires · Bootstrap connects role policy into the app.
- app.js → blockchain.js: wires · Bootstrap connects the ledger engine.
- app.js → ui.js: wires · Bootstrap connects controller and view.
- ui.js → roles.js: checks · UI gates available actions by role.
- ui.js → blockchain.js: invokes · User actions create blocks or request validation.
- blockchain.js → CryptoJS: hashes · Block digests are computed with SHA-256.
- blockchain.js → localStorage: persists · Ledger state is stored locally in the browser.
- blockchain.js → Cattle ledger: manages · The engine owns the traceability chain as a whole.
- Cattle ledger → Block record: contains · The ledger is composed of linked block records.
- Verificador → Validation: drives · Verifier role initiates integrity checks.
- Validation → blockchain.js: recomputes · Validation walks the chain from genesis forward.
- Originador → blockchain.js: creates · Originator role adds registration records.
- Agregador → blockchain.js: appends · Aggregator role adds sanitary and vaccination events.
- Verificador → blockchain.js: inspects · Verifier role reads and audits the chain.
- ui.js → QR output: renders · The interface displays QR artifacts for inspection.
- QR output → QRCode.js: generates · QR code output is produced client-side.
