# swapanrishi/de-centrilized_market_place architecture

> Architecture diagram of the GitHub repository swapanrishi/de-centrilized_market_place, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/swapanrishi/de-centrilized_market_place
- Repository: https://github.com/swapanrishi/de-centrilized_market_place

## Overview

1. **Overall shape**
   BlockMart is a **hybrid dApp marketplace**: user-facing commerce flows are split between an **off-chain web/app layer** for metadata and UX, and an **on-chain settlement layer** for escrow and asset transfer. The main architectural boundary is between **fast relational data handling** and **trustless blockchain execution**.

2. **Frontend subsystem**
   The `frontend/` package is a **React + TypeScript** single-page app built with **Vite** and styled with **Tailwind CSS**. It is the primary user interface for browsing, listing, and trading assets, and it likely uses **Ethers.js / wallet connectors** to connect the browser to a crypto wallet for blockchain actions.

3. **Backend subsystem**
   The `backend/` package is a **Node.js backend** (compiled to `backend/dist/index.js`) that acts as the off-chain service boundary. From the repo layout and README, this layer is responsible for serving marketplace metadata, coordinating application state, and persisting data in the relational database through Prisma.

4. **Database / persistence layer**
   The persistent off-chain store is **PostgreSQL**, accessed via **Prisma ORM**. The repo contains Prisma schemas and migrations under both `backend/prisma/` and a root-level `prisma/`, which suggests either:
   - a shared schema reused across parts of the repo, or
   - an earlier/alternate schema location from the project’s evolution.
   For architecture diagrams, treat the database as the off-chain source of truth for **product listings, user metadata, reviews, and other non-transactional content**.

5. **Blockchain subsystem**
   The `blockchain/` package is a separate **Hardhat-based Solidity workspace**. It contains contracts, tests, deployment/ignition modules, and utility scripts. This is the on-chain execution boundary where **escrow, payment settlement, and trust-sensitive logic** live.

6. **On-chain/off-chain split**
   The key data-flow distinction is:
   - **Off-chain:** product images, descriptions, user profiles, reviews, search-friendly marketplace metadata
   - **On-chain:** payment transfer, escrow release, and asset settlement
   The README explicitly positions the design as a gas-efficient hybrid model, with blockchain used only where trustlessness matters.

7. **Transaction lifecycle**
   A typical marketplace flow is:
   1. User browses listings in the frontend.
   2. Listing metadata comes from the backend/database.
   3. User connects a wallet and initiates a blockchain transaction.
   4. Smart contract holds funds in escrow.
   5. The buyer confirms receipt.
   6. The contract releases funds / finalizes settlement.
   This is the core cross-boundary flow the diagram should emphasize.

8. **Smart contract tooling**
   The blockchain package includes:
   - `hardhat.config.ts` for local/testnet chain setup
   - `test/BlockMartEscrow.test.ts` for contract-level verification
   - `ignition/modules/` for deployment orchestration
   - `scripts/send-op-tx.ts` for manual transaction execution
   These files indicate the on-chain side is treated as a standalone deployable system with its own CI/test boundary.

9. **Authentication / legacy entry points**
   The repo also includes `php/login.php`, `php/register.php`, `login-pg.html`, and `RegisterSign.html`. These look like an **alternate or legacy auth path** separate from the React frontend and Node backend. If you draw the architecture, place these as a parallel web entry path rather than part of the main React/Node flow unless the code confirms otherwise.

10. **Containerization and runtime environment**
   The backend has Docker files, indicating it can be packaged independently with its runtime dependencies. The README also calls out Docker for local backend/database environment. That makes the deployment boundary likely:
   - frontend served separately,
   - backend in a container,
   - PostgreSQL as a local or managed service,
   - blockchain contracts deployed to Sepolia for testnet usage.

11. **External dependencies / services**
   The main external service is the **Ethereum Sepolia testnet**, which is the on-chain runtime target. Wallets such as **MetaMask** or **WalletConnect** are also part of the runtime boundary, because they authorize and sign user transactions from the browser.

12. **Repo-level organization**
   The repository is effectively a **multi-package monorepo**:
   - `frontend/` for UI
   - `backend/` for API and database access
   - `blockchain/` for contracts and deployment
   - `php/` plus standalone HTML files for alternate auth pages
   - root-level Prisma assets and package files, suggesting shared or historical infrastructure
   This separation is important for the diagram because it shows three primary runtime domains: browser, server/database, and blockchain.

13. **What to emphasize in the diagram**
   The most important architecture boundaries are:
   - **Browser ↔ Backend** for marketplace metadata and app state
   - **Browser ↔ Wallet ↔ Blockchain** for signing and escrow transactions
   - **Backend ↔ PostgreSQL/Prisma** for persistent off-chain data
   - **Contracts ↔ Sepolia** for settlement execution
   If you only highlight one thing, highlight the **hybrid split between off-chain commerce data and on-chain settlement logic**.

Main entry points: [`backend/src/index.ts`](https://github.com/swapanrishi/de-centrilized_market_place/blob/main/backend/src/index.ts) (API Server), [`frontend/src/App.tsx`](https://github.com/swapanrishi/de-centrilized_market_place/blob/main/frontend/src/App.tsx) (Marketplace UI), [`backend/prisma/schema.prisma`](https://github.com/swapanrishi/de-centrilized_market_place/blob/main/backend/prisma/schema.prisma) (DB Schema), [`blockchain/hardhat.config.ts`](https://github.com/swapanrishi/de-centrilized_market_place/blob/main/blockchain/hardhat.config.ts) (Hardhat Config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser App"]
  node_frontend_app["Marketplace UI<br/>React SPA<br/>[App.tsx]"]
  node_frontend_boot["App Entry<br/>Vite entry<br/>[main.tsx]"]
  node_frontend_styles["UI Styling<br/>Tailwind CSS<br/>[index.css]"]
end

subgraph group_offchain["Off-chain Service"]
  node_backend_entry["API Server<br/>Node service<br/>[index.ts]"]
  node_backend_runtime["Built Server<br/>compiled JS<br/>[index.js]"]
  node_backend_schema["DB Schema<br/>Prisma schema<br/>[schema.prisma]"]
  node_root_schema["Shared Schema<br/>Prisma schema<br/>[schema.prisma]"]
  node_db_migrations["Migrations<br/>[migration.sql]"]
end

subgraph group_blockchain["On-chain System"]
  node_blockchain_config["Hardhat Config<br/>[hardhat.config.ts]"]
  node_escrow_tests["Escrow Tests<br/>contract test"]
  node_deploy_module["Deploy Module<br/>ignition module<br/>[Counter.ts]"]
  node_tx_script["Tx Script<br/>[send-op-tx.ts]"]
end

subgraph group_legacy["Legacy Web"]
  node_legacy_login["Legacy Login<br/>PHP auth<br/>[login.php]"]
  node_legacy_register["Legacy Register<br/>PHP auth<br/>[register.php]"]
  node_legacy_login_page["Auth Page<br/>HTML entry<br/>[login-pg.html]"]
  node_legacy_register_page["Auth Page<br/>HTML entry<br/>[RegisterSign.html]"]
end

node_wallet(("Wallet<br/>browser signer"))
node_sepolia{{"Sepolia<br/>Ethereum testnet"}}

node_frontend_boot -->|"mounts"| node_frontend_app
node_frontend_app -->|"styles"| node_frontend_styles
node_frontend_app -->|"fetches metadata"| node_backend_entry
node_frontend_app -->|"signs tx"| node_wallet
node_wallet -->|"submits tx"| node_sepolia
node_backend_entry -->|"reads/writes"| node_backend_schema
node_backend_entry -.->|"uses model"| node_root_schema
node_backend_schema -->|"evolves via"| node_db_migrations
node_backend_runtime -->|"deploys"| node_backend_entry
node_backend_entry -->|"serves data"| node_frontend_app
node_blockchain_config -->|"orchestrates"| node_deploy_module
node_deploy_module -->|"deploys to"| node_sepolia
node_escrow_tests -->|"verifies"| node_blockchain_config
node_tx_script -->|"executes on"| node_sepolia
node_frontend_app -->|"initiates escrow"| node_sepolia
node_legacy_login_page -.->|"links to"| node_legacy_login
node_legacy_register_page -.->|"links to"| node_legacy_register
node_legacy_login -.->|"parallel auth path"| node_backend_entry
node_legacy_register -.->|"parallel auth path"| node_backend_entry

click node_frontend_app "https://github.com/swapanrishi/de-centrilized_market_place/blob/main/frontend/src/App.tsx"
click node_frontend_boot "https://github.com/swapanrishi/de-centrilized_market_place/blob/main/frontend/src/main.tsx"
click node_frontend_styles "https://github.com/swapanrishi/de-centrilized_market_place/blob/main/frontend/src/index.css"
click node_backend_entry "https://github.com/swapanrishi/de-centrilized_market_place/blob/main/backend/src/index.ts"
click node_backend_runtime "https://github.com/swapanrishi/de-centrilized_market_place/blob/main/backend/dist/index.js"
click node_backend_schema "https://github.com/swapanrishi/de-centrilized_market_place/blob/main/backend/prisma/schema.prisma"
click node_root_schema "https://github.com/swapanrishi/de-centrilized_market_place/blob/main/prisma/schema.prisma"
click node_db_migrations "https://github.com/swapanrishi/de-centrilized_market_place/blob/main/backend/prisma/migrations/20260425124057_init/migration.sql"
click node_blockchain_config "https://github.com/swapanrishi/de-centrilized_market_place/blob/main/blockchain/hardhat.config.ts"
click node_escrow_tests "https://github.com/swapanrishi/de-centrilized_market_place/blob/main/blockchain/test/BlockMartEscrow.test.ts"
click node_deploy_module "https://github.com/swapanrishi/de-centrilized_market_place/blob/main/blockchain/ignition/modules/Counter.ts"
click node_tx_script "https://github.com/swapanrishi/de-centrilized_market_place/blob/main/blockchain/scripts/send-op-tx.ts"
click node_legacy_login "https://github.com/swapanrishi/de-centrilized_market_place/blob/main/php/login.php"
click node_legacy_register "https://github.com/swapanrishi/de-centrilized_market_place/blob/main/php/register.php"
click node_legacy_login_page "https://github.com/swapanrishi/de-centrilized_market_place/blob/main/login-pg.html"
click node_legacy_register_page "https://github.com/swapanrishi/de-centrilized_market_place/blob/main/RegisterSign.html"

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_frontend_boot,node_frontend_styles toneBlue
class node_backend_entry,node_backend_runtime,node_backend_schema,node_root_schema,node_db_migrations toneAmber
class node_blockchain_config,node_escrow_tests,node_deploy_module,node_tx_script toneMint
class node_legacy_login,node_legacy_register,node_legacy_login_page,node_legacy_register_page toneRose
class node_wallet,node_sepolia toneNeutral
```

## Components

### Browser App

React/Vite SPA for marketplace browsing, listing, and wallet-driven transactions.

- [Marketplace UI](https://github.com/swapanrishi/de-centrilized_market_place/blob/main/frontend/src/App.tsx): React SPA · Main user interface for browsing listings, trading assets, and initiating wallet actions. · `frontend/src/App.tsx`
- [App Entry](https://github.com/swapanrishi/de-centrilized_market_place/blob/main/frontend/src/main.tsx): Vite entry · Client bootstrap and app mounting for the SPA. · `frontend/src/main.tsx`
- [UI Styling](https://github.com/swapanrishi/de-centrilized_market_place/blob/main/frontend/src/index.css): Tailwind CSS · Presentation layer and global styling for the browser app. · `frontend/src/index.css`

### Off-chain Service

Node backend and Prisma-backed persistence for marketplace metadata and app state.

- [API Server](https://github.com/swapanrishi/de-centrilized_market_place/blob/main/backend/src/index.ts): Node service · Backend process that serves the off-chain service boundary and application state. · `backend/src/index.ts`
- [Built Server](https://github.com/swapanrishi/de-centrilized_market_place/blob/main/backend/dist/index.js): compiled JS · Packaged backend runtime entry used for deployment. · `backend/dist/index.js`
- [DB Schema](https://github.com/swapanrishi/de-centrilized_market_place/blob/main/backend/prisma/schema.prisma): Prisma schema · Primary backend data model for marketplace metadata and persistence. · `backend/prisma/schema.prisma`
- [Shared Schema](https://github.com/swapanrishi/de-centrilized_market_place/blob/main/prisma/schema.prisma): Prisma schema · Root-level Prisma schema, likely shared or legacy database definition. · `prisma/schema.prisma`
- [Migrations](https://github.com/swapanrishi/de-centrilized_market_place/blob/main/backend/prisma/migrations/20260425124057_init/migration.sql): Prisma migrations · Database evolution history for the relational store. · `backend/prisma/migrations/20260425124057_init/migration.sql`

### On-chain System

Hardhat Solidity workspace for escrow, deployment, and settlement logic.

- [Hardhat Config](https://github.com/swapanrishi/de-centrilized_market_place/blob/main/blockchain/hardhat.config.ts): Hardhat config · Chain and tooling configuration for the Solidity workspace. · `blockchain/hardhat.config.ts`
- [Escrow Tests](https://github.com/swapanrishi/de-centrilized_market_place/blob/main/blockchain/test/BlockMartEscrow.test.ts): contract test · Contract-level verification for marketplace settlement behavior. · `blockchain/test/BlockMartEscrow.test.ts`
- [Deploy Module](https://github.com/swapanrishi/de-centrilized_market_place/blob/main/blockchain/ignition/modules/Counter.ts): ignition module · Deployment orchestration for on-chain contracts. · `blockchain/ignition/modules/Counter.ts`
- [Tx Script](https://github.com/swapanrishi/de-centrilized_market_place/blob/main/blockchain/scripts/send-op-tx.ts): script · Manual transaction helper for sending on-chain operations. · `blockchain/scripts/send-op-tx.ts`

### Legacy Web

Alternate PHP/HTML entry points separate from the main React + Node flow.

- [Legacy Login](https://github.com/swapanrishi/de-centrilized_market_place/blob/main/php/login.php): PHP auth · Alternate login page outside the main SPA flow. · `php/login.php`
- [Legacy Register](https://github.com/swapanrishi/de-centrilized_market_place/blob/main/php/register.php): PHP auth · Alternate registration page outside the main SPA flow. · `php/register.php`
- [Auth Page](https://github.com/swapanrishi/de-centrilized_market_place/blob/main/login-pg.html): HTML entry · Standalone HTML login/register entry point. · `login-pg.html`
- [Auth Page](https://github.com/swapanrishi/de-centrilized_market_place/blob/main/RegisterSign.html): HTML entry · Standalone HTML sign-up entry point. · `RegisterSign.html`

### Other components

- **Wallet**: browser signer · External wallet connector used to sign marketplace transactions.
- **Sepolia**: Ethereum testnet · External blockchain runtime where settlement and escrow execute.

## Connections

- App Entry → Marketplace UI: mounts · Bootstraps the React marketplace UI.
- Marketplace UI → UI Styling: styles · Uses shared Tailwind/global styling.
- Marketplace UI → API Server: fetches metadata · Browser UI loads listings and marketplace state from the backend.
- Marketplace UI → Wallet: signs tx · Connects to a browser wallet for user authorization.
- Wallet → Sepolia: submits tx · Wallet relays signed transactions to the blockchain network.
- API Server → DB Schema: reads/writes · Backend persists off-chain marketplace data through Prisma.
- API Server → Shared Schema: uses model · Backend may rely on the root Prisma schema as a shared or legacy definition.
- DB Schema → Migrations: evolves via · Schema changes are applied through migrations.
- Built Server → API Server: deploys · Built artifact packages the server for runtime deployment.
- API Server → Marketplace UI: serves data · Provides marketplace metadata and application state to the UI.
- Hardhat Config → Deploy Module: orchestrates · Hardhat configuration drives deployment modules.
- Deploy Module → Sepolia: deploys to · Deploys smart contracts onto the target network.
- Escrow Tests → Hardhat Config: verifies · Tests run against the configured Hardhat environment.
- Tx Script → Sepolia: executes on · Manual script sends transactions to the testnet.
- Marketplace UI → Sepolia: initiates escrow · User-facing commerce flow triggers on-chain settlement actions.
- Auth Page → Legacy Login: links to · Standalone HTML entry can route into the PHP auth flow.
- Auth Page → Legacy Register: links to · Standalone HTML entry can route into the PHP auth flow.
- Legacy Login → API Server: parallel auth path · Separate web entry path that may overlap with the main service boundary.
- Legacy Register → API Server: parallel auth path · Separate web entry path that may overlap with the main service boundary.