# deyber13013/registro-documentos-blockchain architecture

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

- Interactive diagram: https://gitdiagram.com/deyber13013/registro-documentos-blockchain
- Repository: https://github.com/deyber13013/registro-documentos-blockchain

## Overview

1. **Overall shape**
   - This repo is a decentralized document registry dApp with a **hybrid architecture**: document bytes live off-chain in **IPFS via Pinata**, while the immutable proof of existence lives on-chain in a **Solidity smart contract** deployed to **Polygon Amoy**.
   - The key architectural boundary is that the chain stores only the minimal verification data, not the document itself.

2. **Main subsystems**
   - **Frontend app (`frontend/`)**: Next.js 15 App Router UI for upload, registration, and lookup.
   - **Blockchain app layer**: `frontend/src/blockchain.js` and `frontend/src/constants/` centralize provider, network, and contract configuration for client-side Web3 calls.
   - **Smart contract layer (`contracts/`)**: the registry logic that persists document proofs and exposes read/write methods.
   - **Deployment layer (`hardhat.config.js`, `ignition/`)**: Hardhat + Ignition manage compilation and deployment to local and test networks.
   - **Stored deployment artifacts (`ignition/deployments/`)**: saved addresses/build info for chain `31337` and `80002`, supporting repeatable frontend integration.

3. **User-facing data flow**
   - A user selects a file in the frontend.
   - The frontend uploads the binary file to **Pinata/IPFS**.
   - IPFS returns a **CID**, which the system treats as the document’s cryptographic identifier.
   - The frontend then asks **MetaMask** to sign and send the on-chain transaction.
   - The smart contract records the CID plus provenance metadata, and the UI shows the receipt/result.

4. **Off-chain storage boundary**
   - IPFS is used only for **content-addressed file storage**.
   - Pinata adds the persistence/pinning layer so the uploaded document remains available.
   - This off-chain layer is where file bytes are stored and where the CID is derived; no business state is trusted to the browser alone.

5. **On-chain registry boundary**
   - The contract acts as an immutable registry for document proofs.
   - From the README, the stored record includes the **CID/hash**, **timestamp**, and **owner address**.
   - The on-chain mapping provides **O(1)** lookup for existence and retrieval by hash/CID, making the blockchain the source of truth for verification.

6. **Validation / audit flow**
   - The auditing path is read-heavy: the user enters a CID/hash into the UI.
   - The frontend queries the contract directly for that identifier.
   - If present, the UI can reconstruct the certificate data: who registered it, when it was registered, and the CID that points back to IPFS.

7. **Frontend architecture**
   - The UI is a **Next.js 15** client application, with the root page and layout under `frontend/src/app/`.
   - `frontend/src/blockchain.js` is the key integration boundary between React UI and blockchain providers/contracts.
   - `frontend/src/constants/` likely holds network IDs, contract addresses, and API/environment values needed to switch between local and testnet deployment targets.

8. **Smart contract/deployment architecture**
   - Hardhat is the build and dev environment for Solidity.
   - Ignition modules in `ignition/modules/DocumentRegistry.js` define deployment orchestration for the registry contract.
   - The checked-in `ignition/deployments/` folders for `chain-31337` and `chain-80002` show that the repo supports both **local development** and **Polygon Amoy** deployment targets.

9. **External services and trust model**
   - **MetaMask** is the user’s wallet and transaction signer; the backend never holds private keys.
   - **Pinata/IPFS** is the external storage service; its JWT/API access is required for upload/pinning.
   - **Polygon Amoy** provides the immutable settlement layer; the contract address and network selection determine where proofs are written.

10. **Important architectural constraint**
   - The system intentionally avoids storing document contents on-chain to reduce gas costs and improve scalability.
   - The design assumes that **content identity equals CID**, so any byte-level modification produces a different identifier and invalidates the original proof.

11. **What to draw in an architecture diagram**
   - Show three trust zones: **browser/UI**, **off-chain IPFS storage**, and **on-chain Polygon contract**.
   - Put **MetaMask** between UI and blockchain as the signing/transaction gateway.
   - Add the **Hardhat/Ignition deployment path** as a separate engineering path feeding contract addresses into the frontend.
   - Emphasize that the main runtime data loop is: file upload → CID generation → transaction signing → registry write → read-back verification.

Main entry points: [`frontend/src/app/page.js`](https://github.com/deyber13013/registro-documentos-blockchain/blob/main/frontend/src/app/page.js) (Registry UI), [`frontend/src/blockchain.js`](https://github.com/deyber13013/registro-documentos-blockchain/blob/main/frontend/src/blockchain.js) (Blockchain bridge), [`ignition/modules/DocumentRegistry.js`](https://github.com/deyber13013/registro-documentos-blockchain/blob/main/ignition/modules/DocumentRegistry.js) (Ignition module), [`contracts`](https://github.com/deyber13013/registro-documentos-blockchain/tree/main/contracts) (Registry contract)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser UI"]
  node_frontend_app["Frontend app<br/>Next.js 15"]
  node_page["Registry UI<br/>App page<br/>[page.js]"]
  node_layout["App shell<br/>Layout<br/>[layout.js]"]
  node_blockchain_js["Blockchain bridge<br/>Web3 integration<br/>[blockchain.js]"]
  node_constants["Chain config<br/>Runtime config<br/>[index.js]"]
  node_metamask{{"MetaMask<br/>Wallet signer"}}
end

subgraph group_storage["Off-chain storage"]
  node_pinata[("Pinata<br/>Pinning service")]
  node_ipfs[("IPFS<br/>Content store")]
end

subgraph group_chain["On-chain registry"]
  node_registry_contract["Registry contract<br/>Solidity registry"]
  node_polygon_amoy{{"Polygon Amoy<br/>Testnet"}}
end

subgraph group_deploy["Deployment"]
  node_hardhat["Hardhat<br/>Build tool<br/>[hardhat.config.js]"]
  node_ignition_module["Ignition module<br/>Deployment plan"]
  node_deploy_31337["Local deploy<br/>Artifacts 31337"]
  node_deploy_80002["Amoy deploy<br/>Artifacts 80002"]
end

node_frontend_app -->|"renders"| node_page
node_frontend_app -->|"uses"| node_layout
node_page -->|"uploads"| node_pinata
node_pinata -->|"stores"| node_ipfs
node_ipfs -->|"returns CID"| node_page
node_page -->|"delegates"| node_blockchain_js
node_blockchain_js -->|"reads config"| node_constants
node_blockchain_js -->|"signs tx"| node_metamask
node_metamask -->|"submits"| node_polygon_amoy
node_blockchain_js -->|"writes/reads"| node_registry_contract
node_registry_contract -->|"deployed on"| node_polygon_amoy
node_page -->|"verifies"| node_registry_contract
node_hardhat -->|"drives"| node_ignition_module
node_ignition_module -->|"deploys"| node_registry_contract
node_ignition_module -->|"writes"| node_deploy_31337
node_ignition_module -->|"writes"| node_deploy_80002
node_deploy_31337 -->|"feeds"| node_constants
node_deploy_80002 -->|"feeds"| node_constants

click node_frontend_app "https://github.com/deyber13013/registro-documentos-blockchain/tree/main/frontend/src/app"
click node_page "https://github.com/deyber13013/registro-documentos-blockchain/blob/main/frontend/src/app/page.js"
click node_layout "https://github.com/deyber13013/registro-documentos-blockchain/blob/main/frontend/src/app/layout.js"
click node_blockchain_js "https://github.com/deyber13013/registro-documentos-blockchain/blob/main/frontend/src/blockchain.js"
click node_constants "https://github.com/deyber13013/registro-documentos-blockchain/blob/main/frontend/src/constants/index.js"
click node_registry_contract "https://github.com/deyber13013/registro-documentos-blockchain/tree/main/contracts"
click node_hardhat "https://github.com/deyber13013/registro-documentos-blockchain/blob/main/hardhat.config.js"
click node_ignition_module "https://github.com/deyber13013/registro-documentos-blockchain/blob/main/ignition/modules/DocumentRegistry.js"
click node_deploy_31337 "https://github.com/deyber13013/registro-documentos-blockchain/blob/main/ignition/deployments/chain-31337/deployed_addresses.json"
click node_deploy_80002 "https://github.com/deyber13013/registro-documentos-blockchain/blob/main/ignition/deployments/chain-80002/deployed_addresses.json"

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_frontend_app,node_page,node_layout,node_blockchain_js,node_constants,node_metamask toneBlue
class node_pinata,node_ipfs toneAmber
class node_registry_contract,node_polygon_amoy toneMint
class node_hardhat,node_ignition_module,node_deploy_31337,node_deploy_80002 toneRose
```

## Components

### Browser UI

Next.js frontend and wallet-driven user flows

- [Frontend app](https://github.com/deyber13013/registro-documentos-blockchain/tree/main/frontend/src/app): Next.js 15 · Client application for upload, registration, and lookup · `frontend/src/app`
- [Registry UI](https://github.com/deyber13013/registro-documentos-blockchain/blob/main/frontend/src/app/page.js): App page · Primary screen for selecting files and searching CIDs · `frontend/src/app/page.js`
- [App shell](https://github.com/deyber13013/registro-documentos-blockchain/blob/main/frontend/src/app/layout.js): Layout · Root UI shell and shared page framing · `frontend/src/app/layout.js`
- [Blockchain bridge](https://github.com/deyber13013/registro-documentos-blockchain/blob/main/frontend/src/blockchain.js): Web3 integration · Client-side boundary for providers, contract calls, and transaction flow · `frontend/src/blockchain.js`
- [Chain config](https://github.com/deyber13013/registro-documentos-blockchain/blob/main/frontend/src/constants/index.js): Runtime config · Network IDs, contract addresses, and environment values · `frontend/src/constants/index.js`
- **MetaMask**: Wallet signer · Browser wallet used to sign and submit transactions

### Off-chain storage

Content-addressed file storage and pinning

- **Pinata**: Pinning service · Persistence layer for uploaded document bytes
- **IPFS**: Content store · Content-addressed storage that returns the CID

### On-chain registry

Solidity registry and Polygon settlement

- [Registry contract](https://github.com/deyber13013/registro-documentos-blockchain/tree/main/contracts): Solidity registry · On-chain proof registry for CID, timestamp, and owner · `contracts`
- **Polygon Amoy**: Testnet · Settlement network where proofs are written immutably

### Deployment

Hardhat and Ignition deployment path

- [Hardhat](https://github.com/deyber13013/registro-documentos-blockchain/blob/main/hardhat.config.js): Build tool · Compilation and local/test deployment environment · `hardhat.config.js`
- [Ignition module](https://github.com/deyber13013/registro-documentos-blockchain/blob/main/ignition/modules/DocumentRegistry.js): Deployment plan · Deployment orchestration for the document registry · `ignition/modules/DocumentRegistry.js`
- [Local deploy](https://github.com/deyber13013/registro-documentos-blockchain/blob/main/ignition/deployments/chain-31337/deployed_addresses.json): Artifacts 31337 · Saved deployment state for local development chain · `ignition/deployments/chain-31337/deployed_addresses.json`
- [Amoy deploy](https://github.com/deyber13013/registro-documentos-blockchain/blob/main/ignition/deployments/chain-80002/deployed_addresses.json): Artifacts 80002 · Saved deployment state for Polygon Amoy · `ignition/deployments/chain-80002/deployed_addresses.json`

## Connections

- Frontend app → Registry UI: renders · Root app serves the registry UI
- Frontend app → App shell: uses · Shared shell wraps the page
- Registry UI → Pinata: uploads · Selected file is sent to the pinning service
- Pinata → IPFS: stores · Pinned content becomes addressable by CID
- IPFS → Registry UI: returns CID · CID is surfaced back to the UI
- Registry UI → Blockchain bridge: delegates · UI hands Web3 actions to the blockchain bridge
- Blockchain bridge → Chain config: reads config · Provider and contract details come from shared constants
- Blockchain bridge → MetaMask: signs tx · Wallet signs and sends on-chain transactions
- MetaMask → Polygon Amoy: submits · Signed transaction is broadcast to the network
- Blockchain bridge → Registry contract: writes/reads · Client calls registry methods for registration and lookup
- Registry contract → Polygon Amoy: deployed on · Contract state lives on the testnet
- Registry UI → Registry contract: verifies · Lookup flow queries the registry for an existing CID
- Hardhat → Ignition module: drives · Hardhat compiles and feeds deployment orchestration
- Ignition module → Registry contract: deploys · Module instantiates the registry contract
- Ignition module → Local deploy: writes · Local deployment addresses are recorded
- Ignition module → Amoy deploy: writes · Amoy deployment addresses are recorded
- Local deploy → Chain config: feeds · Local addresses support frontend integration
- Amoy deploy → Chain config: feeds · Amoy addresses support frontend integration
