Blockchain is NOT your database — hybrid design rules

When I was building ProofChain — a proof-of-existence system where you can register a document on the blockchain and prove it hasn't been tampered with — I hit the wall instantly.

My first instinct: store everything on-chain. The document. The metadata. The owner. The timestamp. The filename.

I calculated the gas cost for storing a 50MB PDF on Ethereum.

$47,000 per upload.

I stared at that number for a full minute. Then I understood the fundamental rule that every enterprise Web3 architect eventually learns the hard way:

The blockchain is not your database. It's your notary.

1. The Core Principle: Defining the Trust Boundary

When modeling an enterprise system (like a decentralized pharmaceutical supply chain), you must inspect every data variable and ask:

Does this variable require mathematical consensus or double-spend protection?
            │
            ├─────────────── Yes ──────────────> [ ON-CHAIN STORAGE ] (Ledger State)
            │
            └─────────────── No ───────────────> [ OFF-CHAIN STORAGE ] (IPFS / Database)

• On-Chain Candidates: Token ownership mappings, cryptographic hashes of documents, supply chain state transitions, and authorization registries. These require consensus and absolute immutability.
• Off-Chain Candidates: User avatars, item descriptions, employee profile details, transaction history tables, and search indexes. These belong in standard databases or decentralized file stores.

2. The Hybrid Enterprise Web3 Stack

A production-grade Web3 architecture separates execution, storage, and querying into three highly specialized layers:

+-------------------------------------------------------------------+
|                     ENTERPRISE HYBRID STACK                       |
|                                                                   |
|   [ FRONTEND CLIENT ] (Next.js Application)                       |
|           │                   │                    │              |
|           ▼ (Gasless Reads)   ▼ (Upload Metadata)  ▼ (State Writs)|
|     [ CACHE LAYER ]     [ FILE STORAGE ]     [ LEDGER STATE ]     |
|    (Firebase / SQL)    (IPFS / Arweave)     (Smart Contracts)     |
|           ▲                                        │              |
|           │                                        ▼              |
|           └─────────── [ INDEXING ENGINE ] ────────┘              |
|                      (The Graph / Subgraph)                       |
+-------------------------------------------------------------------+

1. The Ledger Layer (Smart Contracts): Executes the state machine, verifies cryptographic signatures, and records proof hashes.
2. The Decentralized File Layer (IPFS): Acts as a global, immutable hard drive. Larger files are uploaded here and referenced via their unique Content Identifier (CID) hash.
3. The Indexing Layer (The Graph): Listens to contract events in real-time, processes transactions, and maintains a highly optimized GraphQL search index.
4. The Cache Layer (Databases): Pulls pre-processed data from the indexing engine, serving instant search results (like fuzzy matching and chronological sorting) to the client UI.

3. ProofChain: The Real Example

ProofChain is a proof-of-existence system. You upload a document. It proves it existed at a specific moment, unchanged, with a specific owner. Here is exactly how the hybrid architecture makes this possible:

FILE (50MB PDF)
  │
  ├─► Browser hashes it: SHA-256 → 0x9a8f... (32 bytes)
  │
  ├─► Browser uploads PDF to IPFS → CID: QmXyZ...
  │
  └─► User signs: registerProof(0x9a8f...) → blockchain
                    │
                    Only 32 bytes on-chain.
                    Gas cost: ~$0.002.
                    (vs $47,000 to store the PDF itself)

FIREBASE (off-chain cache)
  │
  Stores: { hash: "0x9a8f...", cid: "QmXyZ...",
            filename: "contract.pdf", ownerId: "user123",
            timestamp: 1716000000 }
  │
  Serves: instant search, sort, filter, dashboard

THE GRAPH (indexing)
  │
  Listens to: ProofLogged(hash, owner) events
  Serves: historical proof registry, owner lookup

If anyone alters a single pixel in the PDF sitting on IPFS, their recomputed hash will mismatch 0x9a8f... — the fingerprint permanently written to the chain. The tamper is immediately provable.

Notice what the blockchain stores: 32 bytes. Not the file. Not the metadata. Not the owner's name. Just the cryptographic fingerprint.

Notice what Firebase stores: everything humans actually need to browse and search.

Notice what The Graph indexes: the on-chain event history, so the frontend can query "all documents registered by this wallet" in milliseconds.

The blockchain is the notary. Firebase is the filing cabinet. IPFS is the vault.