How deyber13013/registro-documentos-blockchain works
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: page.js Registry UI · blockchain.js Blockchain bridge · DocumentRegistry.js Ignition module · contracts Registry contract
Components 14
Browser UI
Next.js frontend and wallet-driven user flows
- Frontend app · Client application for upload, registration, and lookup
frontend/src/app - Registry UI · Primary screen for selecting files and searching CIDs
frontend/src/app/page.js - App shell · Root UI shell and shared page framing
frontend/src/app/layout.js - Blockchain bridge · Client-side boundary for providers, contract calls, and transaction flow
frontend/src/blockchain.js - Chain config · Network IDs, contract addresses, and environment values
frontend/src/constants/index.js - MetaMask · Browser wallet used to sign and submit transactions
Off-chain storage
Content-addressed file storage and pinning
- Pinata · Persistence layer for uploaded document bytes
- IPFS · Content-addressed storage that returns the CID
On-chain registry
Solidity registry and Polygon settlement
- Registry contract · On-chain proof registry for CID, timestamp, and owner
contracts - Polygon Amoy · Settlement network where proofs are written immutably
Deployment
Hardhat and Ignition deployment path
- Hardhat · Compilation and local/test deployment environment
hardhat.config.js - Ignition module · Deployment orchestration for the document registry
ignition/modules/DocumentRegistry.js - Local deploy · Saved deployment state for local development chain
ignition/deployments/chain-31337/deployed_addresses.json - Amoy deploy · Saved deployment state for Polygon Amoy
ignition/deployments/chain-80002/deployed_addresses.json
Connections 18
- 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