IPFS Ethereum File Storage Project – BlockFiles

Overview

The goal for BlockFiles was to design a storage workflow where the payload and proof are deliberately separated. File bytes are pinned to IPFS and represented by a CID, while ownership and update events are anchored through smart contract writes. This architecture lets users verify whether a document is the same object they originally uploaded, even when accessed from a different gateway or shared outside the app.

From a product perspective, BlockFiles behaves like a normal upload app: users can create a project, upload files, attach tags, and search records. Under the hood, every step creates a provenance trail. I focused on making the technical guarantees useful in real day-to-day operations, not just in a demo environment. That meant building clear status indicators, predictable retry behavior, and searchable metadata so people could trust the system without understanding blockchain internals.

Problem

Conventional cloud storage is convenient, but ownership assertions are weak once files move between teams, vendors, or legal boundaries. If a file is renamed, copied, or exported, proving which version was original usually requires trusting logs from one provider. In compliance-heavy use cases, this creates operational friction and disputes around document authenticity.

A second challenge is discoverability. Some decentralized storage demos prove immutability but ignore retrieval workflows, so users end up with hashes and no practical way to find content quickly. For BlockFiles to be usable, I needed both verifiability and useful search. That shaped decisions around metadata modeling, index design, and a hybrid read path where index queries remain fast while content verification still traces back to CIDs and on-chain events.

Approach

I treated this project as a layered trust system. First, uploads are validated and chunked before pinning to IPFS. Second, normalized metadata is written to a relational store to power filtering and fast result pages. Third, core ownership state is written to Ethereum so that critical lifecycle transitions are externally auditable. This gives users a practical interface while preserving a non-repudiable audit path.

I also optimized for a realistic cost profile. Writing every action on-chain makes UX and operations expensive, so BlockFiles records high-value events on-chain and keeps volatile query data off-chain. A deterministic mapping between metadata records and CID references preserves traceability. This tradeoff improved interaction speed while retaining the security properties that matter for ownership and tamper evidence.

Architecture

The runtime architecture combines asynchronous storage and transaction workflows with an indexed API layer. I used background jobs for tasks that could fail due to network volatility, and synchronous API handlers only for operations that need immediate feedback. This separation kept the app responsive under intermittent node latency.

The stack was deployed as containerized services for consistency between local development and production. The frontend is deployed on Vercel for fast global delivery, and backend services are built to run in Docker with environment-isolated secrets for blockchain RPC, pinning credentials, and database access.

• - React + Next.js interface for uploads, document listing, search, and ownership timeline rendering.
• - Node.js and Express API for authentication, metadata validation, CID registration, and ownership event orchestration.
• - IPFS pinning workflow with deterministic CID mapping and gateway fallback strategy for resilient retrieval.
• - Ethereum smart contract for ownership registration, transfer events, and integrity-linked references.
• - PostgreSQL metadata index for filtering by user, project, type, upload date, and document tags.
• - Worker queue for asynchronous retry on transaction confirmation and pinning edge-case recovery.
• - Docker-based service packaging and environment profiles for repeatable deploys across staging and production.

What I Built

I built BlockFiles as an end-to-end product, not just a smart contract prototype. The key deliverable was an interface where technical guarantees are visible to non-blockchain users. Most implementation time went into reliability and clarity: users needed to see what happened when a transaction is pending, which CID is tied to a file, and whether the ownership state is confirmed.

Search and retrieval were equally important. I designed query paths so users can search with human labels first, then drill into verifiable metadata and open the exact CID-backed record. This design keeps the experience practical for teams handling many files while preserving the trust model.

• - File upload pipeline with MIME checks, size controls, and deterministic hash validation before pinning.
• - Ownership registration flow that writes smart contract events after storage confirmation.
• - Document detail view with CID visibility, chain transaction links, and clear verification status messaging.
• - Role-aware access controls for project-level organization and document-level action permissions.
• - Search UI with indexed metadata filtering and fallback lookup for direct CID queries.
• - Retry and reconciliation utilities for transaction lag and IPFS gateway inconsistencies.
• - Operational dashboards for upload throughput, pin failures, and chain confirmation timing.

Challenges & Tradeoffs

The hardest part was handling blockchain latency without making the interface feel unreliable. A single failed transaction can come from many causes: low gas settings, congestion, RPC issues, or user wallet interruptions. I added explicit lifecycle states and retry logic so users could distinguish temporary delays from actual failures. That reduced support noise and improved trust.

Another tradeoff involved privacy and transparency. On-chain records are public by default, so sensitive file content cannot live there. BlockFiles stores only essential ownership references and never raw private payloads on-chain. Metadata design had to balance discoverability with minimum disclosure. I used scoped indexing and omitted sensitive fields from public traces while keeping enough linkage for integrity verification.

Results

BlockFiles shipped as a working product with a reliable upload-to-proof workflow. In internal usage tests, users could trace file ownership and integrity in a few clicks instead of digging through provider logs. The hybrid architecture improved perceived responsiveness versus fully on-chain approaches, while still maintaining verifiable provenance for high-value events.

The project also delivered strong engineering learnings. I improved my understanding of where blockchain creates actual product value and where it introduces cost without user benefit. By measuring confirmation times, retry rates, and search latency, I learned how to prioritize practical trust guarantees. The final system proved that decentralized storage can be usable for real document workflows when UX, indexing, and cost control are treated as first-class concerns.

Tech Stack

• React
• Node.js
• Express
• IPFS
• Ethereum
• Solidity
• PostgreSQL
• Docker
• Vercel

Core implementation used React/Next.js for the UI, Node.js + Express for API logic, Solidity for ownership contracts, PostgreSQL for indexable metadata, and IPFS for content-addressed storage. Docker handled service packaging, and Vercel delivered the frontend quickly with global edge caching for static assets.

For deployment, I used environment-segregated secrets and a clean release process: schema migration, worker rollout, API rollout, then frontend publish. This sequence avoided broken references when new fields were introduced. I also added basic health checks and error tracking around pinning and transaction confirmation, which made operational debugging significantly faster.

Links

I keep this page as the technical case study and use the live app plus repository references for implementation details. If you are solving a similar decentralized storage problem, I can walk through architecture decisions, cost controls, and where to avoid unnecessary chain writes.

For collaboration, use the contact page to discuss adaptation for compliance workflows, secure document pipelines, or production hardening of hybrid Web2/Web3 systems.