# nipundineshan/blockchain-plot-management architecture

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

- Interactive diagram: https://gitdiagram.com/nipundineshan/blockchain-plot-management
- Repository: https://github.com/nipundineshan/blockchain-plot-management

## Overview

1. **Top-level shape**
   - This repo is split into two major deployable parts: `be` is a NestJS backend API, and `fe` is an Angular 18 client.
   - The platform is an RWA/property tokenization system: users register property assets, admins verify them, and approved properties are minted as NFTs on an EVM blockchain.

2. **Primary runtime boundary**
   - In production, the system is configured as a **single-server deployment**: the backend starts the app and serves the built frontend.
   - The backend is therefore the main orchestration layer, while the frontend is a consumer of backend APIs plus wallet/blockchain interactions.

3. **Backend application composition**
   - The NestJS backend is modular and domain-driven, with separate modules for `auth`, `users`, `plots`, `nft`, `blockchain`, `ipfs`, `storage`, `notifications`, `audit-logs`, and `transactions`.
   - `main.ts` is the application entrypoint, and cross-cutting behavior is centralized via interceptors, guards, and a global exception filter.

4. **Core domain model**
   - The central business object is the **plot/property** domain (`plots`), backed by entities such as `PlotEntity`, `LegalDocumentEntity`, and `PropertyImageEntity`.
   - Supporting domains track the lifecycle around a property: user accounts, verification status, notifications, audit trails, blockchain minting state, and transaction metadata.

5. **Authentication and authorization**
   - Auth is JWT-based, with `jwt.strategy`, `jwt-auth.guard`, and role-based access control using `roles.guard` and a roles decorator.
   - User-facing access is segmented by role: regular users, admins, super-admins, and an “authority” role are reflected in both backend controllers and frontend routes/guards.

6. **Property registration and review flow**
   - The normal business flow starts with a user submitting property data and documents through the frontend.
   - Backend controllers in `plots` accept create/update requests, persist the property record, and likely move it into a pending-review state for administrative approval.
   - Admin-facing controllers in the frontend map to review, manage, and verify these submissions.

7. **Minting and blockchain integration**
   - Once a property is approved, the `nft` and `blockchain` modules handle NFT creation and chain interaction.
   - The backend contains a dedicated blockchain service and sync service, plus a `contracts` directory, indicating smart-contract integration is part of the backend side of the system.
   - The readme describes the minting flow clearly: upload metadata to IPFS, call the smart contract, then store the resulting token ID and transaction hash back on the property record.

8. **IPFS and file/storage handling**
   - IPFS is a first-class subsystem via `ipfs.service`, and the project explicitly uses Pinata as the storage gateway.
   - There is also a separate `storage` module with an upload controller, suggesting user-uploaded files and documents are handled independently from chain writes, with IPFS used for token metadata and asset references.

9. **Auditability and observability**
   - The backend uses an `audit-log.interceptor`, `logging.interceptor`, and `transform.interceptor`, plus an exception filter.
   - That means request handling is instrumented centrally for traceability, consistent API shaping, and persistent audit history — important for regulated asset workflows.

10. **Notifications and operational records**
   - The `notifications` module and `audit-logs` module suggest two separate concerns: user/admin communication and immutable process history.
   - The `transactions` entity provides a persisted record of blockchain-related activity, likely tying together on-chain operations with off-chain business state.

11. **Frontend composition**
   - The Angular app is organized around role-based screens: user dashboard/profile, admin dashboard, admin verification, admin NFT minting, authority dashboard, property browsing/details, and document management.
   - This is not a generic CRUD UI; it is structured around the property lifecycle and role-specific workflows.

12. **Frontend service boundary**
   - Shared frontend behavior lives in `core/services`: auth, users, plots, NFTs, Web3, export, and app-state services.
   - `auth.interceptor` attaches credentials to API calls, while route guards enforce role access before a component is loaded.

13. **Web3 and client-side blockchain interaction**
   - The presence of `web3.service` indicates the frontend also participates in wallet or chain-related operations, not just backend API calls.
   - This likely supports wallet connectivity and blockchain verification views, while the backend remains responsible for authoritative state changes and persistence.

14. **External infrastructure**
   - The main external systems materially shaping the architecture are PostgreSQL via TypeORM, Ethereum/EVM smart contracts via Ethers.js, and IPFS via Pinata.
   - Docker is included for containerized deployment, and the repo has backend-compose support, reinforcing the single-server production model.

Main entry points: [`be/src/app.module.ts`](https://github.com/nipundineshan/blockchain-plot-management/blob/main/be/src/app.module.ts) (API shell), [`fe/src/app/app.routes.ts`](https://github.com/nipundineshan/blockchain-plot-management/blob/main/fe/src/app/app.routes.ts) (Routes), [`fe/src/app/core/services`](https://github.com/nipundineshan/blockchain-plot-management/tree/main/fe/src/app/core/services) (Core services), [`be/src/blockchain`](https://github.com/nipundineshan/blockchain-plot-management/tree/main/be/src/blockchain) (Blockchain)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_be_main["App entry<br/>NestJS bootstrap<br/>[main.ts]"]
  node_be_api["API shell<br/>App module<br/>[app.module.ts]"]
  node_be_common["Cross-cutting<br/>filters/interceptors"]
  node_be_auth["Auth<br/>JWT security"]
  node_be_users["Users<br/>identity/admin"]
  node_be_plots["Plots<br/>property domain"]
  node_be_nft["NFTs<br/>minting domain"]
  node_be_chain["Blockchain<br/>EVM integration"]
  node_be_ipfs["IPFS<br/>metadata storage"]
  node_be_storage["Storage<br/>file uploads"]
  node_be_notify["Notifications<br/>messaging"]
  node_be_audit["Audit logs<br/>process history"]
  node_be_tx["Transactions<br/>on-chain records"]
end

subgraph group_frontend["Frontend"]
  node_fe_shell["Client shell<br/>Angular bootstrap<br/>[app.component.ts]"]
  node_fe_routes["Routes<br/>route map<br/>[app.routes.ts]"]
  node_fe_core["Core services<br/>shared client core"]
  node_fe_guards["Route guards<br/>client access control"]
  node_fe_user["User screens<br/>property workflow UI"]
  node_fe_admin["Admin screens<br/>admin workflow UI"]
  node_fe_auth["Auth screens<br/>public access UI"]
  node_fe_chain["Chain verify<br/>wallet/web3 UI"]
end

subgraph group_external["External"]
  node_pg[("PostgreSQL<br/>relational DB")]
  node_evm{{"EVM chain<br/>smart contracts"}}
  node_ipfs_net[("IPFS/Pinata<br/>content gateway")]
end

node_be_main -->|"boots"| node_be_api
node_be_main -->|"configures"| node_be_common
node_be_api -->|"includes"| node_be_auth
node_be_api -->|"includes"| node_be_users
node_be_api -->|"includes"| node_be_plots
node_be_api -->|"includes"| node_be_nft
node_be_api -->|"includes"| node_be_chain
node_be_api -->|"includes"| node_be_ipfs
node_be_api -->|"includes"| node_be_storage
node_be_api -->|"includes"| node_be_notify
node_be_api -->|"includes"| node_be_audit
node_be_api -->|"includes"| node_be_tx
node_be_auth -->|"loads users"| node_be_users
node_be_plots -->|"persists"| node_pg
node_be_users -->|"persists"| node_pg
node_be_nft -->|"uploads metadata"| node_be_ipfs
node_be_nft -->|"mints"| node_be_chain
node_be_chain -->|"writes on-chain"| node_evm
node_be_ipfs -->|"stores"| node_ipfs_net
node_be_storage -->|"uploads files"| node_ipfs_net
node_fe_shell -->|"uses"| node_fe_routes
node_fe_shell -->|"uses"| node_fe_core
node_fe_routes -->|"protects"| node_fe_guards
node_fe_routes -->|"exposes"| node_fe_auth
node_fe_routes -->|"exposes"| node_fe_user
node_fe_routes -->|"exposes"| node_fe_admin
node_fe_routes -->|"exposes"| node_fe_chain
node_fe_core -->|"calls"| node_be_auth
node_fe_core -->|"calls"| node_be_users
node_fe_core -->|"calls"| node_be_plots
node_fe_core -->|"calls"| node_be_nft
node_fe_core -->|"calls"| node_be_chain
node_be_audit -->|"observes"| node_be_common
node_be_tx -->|"records"| node_be_chain

click node_be_main "https://github.com/nipundineshan/blockchain-plot-management/blob/main/be/src/main.ts"
click node_be_api "https://github.com/nipundineshan/blockchain-plot-management/blob/main/be/src/app.module.ts"
click node_be_common "https://github.com/nipundineshan/blockchain-plot-management/tree/main/be/src/common"
click node_be_auth "https://github.com/nipundineshan/blockchain-plot-management/tree/main/be/src/auth"
click node_be_users "https://github.com/nipundineshan/blockchain-plot-management/tree/main/be/src/users"
click node_be_plots "https://github.com/nipundineshan/blockchain-plot-management/tree/main/be/src/plots"
click node_be_nft "https://github.com/nipundineshan/blockchain-plot-management/tree/main/be/src/nft"
click node_be_chain "https://github.com/nipundineshan/blockchain-plot-management/tree/main/be/src/blockchain"
click node_be_ipfs "https://github.com/nipundineshan/blockchain-plot-management/tree/main/be/src/ipfs"
click node_be_storage "https://github.com/nipundineshan/blockchain-plot-management/tree/main/be/src/storage"
click node_be_notify "https://github.com/nipundineshan/blockchain-plot-management/tree/main/be/src/notifications"
click node_be_audit "https://github.com/nipundineshan/blockchain-plot-management/tree/main/be/src/audit-logs"
click node_be_tx "https://github.com/nipundineshan/blockchain-plot-management/tree/main/be/src/transactions"
click node_fe_shell "https://github.com/nipundineshan/blockchain-plot-management/blob/main/fe/src/app/app.component.ts"
click node_fe_routes "https://github.com/nipundineshan/blockchain-plot-management/blob/main/fe/src/app/app.routes.ts"
click node_fe_core "https://github.com/nipundineshan/blockchain-plot-management/tree/main/fe/src/app/core/services"
click node_fe_guards "https://github.com/nipundineshan/blockchain-plot-management/tree/main/fe/src/app/core/guards"
click node_fe_user "https://github.com/nipundineshan/blockchain-plot-management/tree/main/fe/src/app/user-dashboard"
click node_fe_admin "https://github.com/nipundineshan/blockchain-plot-management/tree/main/fe/src/app/admin-dashboard"
click node_fe_auth "https://github.com/nipundineshan/blockchain-plot-management/tree/main/fe/src/app/login"
click node_fe_chain "https://github.com/nipundineshan/blockchain-plot-management/tree/main/fe/src/app/blockchain-verification"

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_be_main,node_be_api,node_be_common,node_be_auth,node_be_users,node_be_plots,node_be_nft,node_be_chain,node_be_ipfs,node_be_storage,node_be_notify,node_be_audit,node_be_tx toneBlue
class node_fe_shell,node_fe_routes,node_fe_core,node_fe_guards,node_fe_user,node_fe_admin,node_fe_auth,node_fe_chain toneAmber
class node_pg,node_evm,node_ipfs_net toneMint
```

## Components

### Backend

NestJS API, domain modules, and server-side orchestration

- [App entry](https://github.com/nipundineshan/blockchain-plot-management/blob/main/be/src/main.ts): NestJS bootstrap · Starts the backend app, configures global concerns, and serves the built client · `be/src/main.ts`
- [API shell](https://github.com/nipundineshan/blockchain-plot-management/blob/main/be/src/app.module.ts): App module · Top-level NestJS module composing backend features · `be/src/app.module.ts`
- [Cross-cutting](https://github.com/nipundineshan/blockchain-plot-management/tree/main/be/src/common): filters/interceptors · Global exception handling, logging, transforms, and audit capture · `be/src/common`
- [Auth](https://github.com/nipundineshan/blockchain-plot-management/tree/main/be/src/auth): JWT security · Login, registration, JWT strategy, and role-based access control · `be/src/auth`
- [Users](https://github.com/nipundineshan/blockchain-plot-management/tree/main/be/src/users): identity/admin · User accounts plus admin and super-admin controllers · `be/src/users`
- [Plots](https://github.com/nipundineshan/blockchain-plot-management/tree/main/be/src/plots): property domain · Core property lifecycle, documents, images, and plot records · `be/src/plots`
- [NFTs](https://github.com/nipundineshan/blockchain-plot-management/tree/main/be/src/nft): minting domain · NFT creation and mint orchestration for approved properties · `be/src/nft`
- [Blockchain](https://github.com/nipundineshan/blockchain-plot-management/tree/main/be/src/blockchain): EVM integration · Chain interaction and synchronization services · `be/src/blockchain`
- [IPFS](https://github.com/nipundineshan/blockchain-plot-management/tree/main/be/src/ipfs): metadata storage · Uploads metadata and asset references through Pinata-backed IPFS · `be/src/ipfs`
- [Storage](https://github.com/nipundineshan/blockchain-plot-management/tree/main/be/src/storage): file uploads · Handles user file and document upload traffic separate from chain writes · `be/src/storage`
- [Notifications](https://github.com/nipundineshan/blockchain-plot-management/tree/main/be/src/notifications): messaging · User and admin notifications around workflow events · `be/src/notifications`
- [Audit logs](https://github.com/nipundineshan/blockchain-plot-management/tree/main/be/src/audit-logs): process history · Persisted audit trail for regulated property operations · `be/src/audit-logs`
- [Transactions](https://github.com/nipundineshan/blockchain-plot-management/tree/main/be/src/transactions): on-chain records · Stores blockchain transaction metadata and outcomes · `be/src/transactions`

### Frontend

Angular client with role-based screens and shared services

- [Client shell](https://github.com/nipundineshan/blockchain-plot-management/blob/main/fe/src/app/app.component.ts): Angular bootstrap · Frontend application shell, configuration, and routing host · `fe/src/app/app.component.ts`
- [Routes](https://github.com/nipundineshan/blockchain-plot-management/blob/main/fe/src/app/app.routes.ts): route map · Role-segmented navigation and screen access · `fe/src/app/app.routes.ts`
- [Core services](https://github.com/nipundineshan/blockchain-plot-management/tree/main/fe/src/app/core/services): shared client core · Auth, plots, users, NFTs, app state, export, and Web3 services · `fe/src/app/core/services`
- [Route guards](https://github.com/nipundineshan/blockchain-plot-management/tree/main/fe/src/app/core/guards): client access control · Auth and role guards for user, admin, super-admin, and authority screens · `fe/src/app/core/guards`
- [User screens](https://github.com/nipundineshan/blockchain-plot-management/tree/main/fe/src/app/user-dashboard): property workflow UI · Register, browse, track approvals, manage documents, and profile views · `fe/src/app/user-dashboard`
- [Admin screens](https://github.com/nipundineshan/blockchain-plot-management/tree/main/fe/src/app/admin-dashboard): admin workflow UI · Property review, user management, verification, minting, and settings · `fe/src/app/admin-dashboard`
- [Auth screens](https://github.com/nipundineshan/blockchain-plot-management/tree/main/fe/src/app/login): public access UI · Landing, login, and registration entry points · `fe/src/app/login`
- [Chain verify](https://github.com/nipundineshan/blockchain-plot-management/tree/main/fe/src/app/blockchain-verification): wallet/web3 UI · Client-side blockchain verification and wallet-related screens · `fe/src/app/blockchain-verification`

### External

Databases, blockchain, and content infrastructure

- **PostgreSQL**: relational DB · Primary persistent store behind the TypeORM-backed backend
- **EVM chain**: smart contracts · Blockchain where approved properties are minted as NFTs
- **IPFS/Pinata**: content gateway · Off-chain metadata and file storage layer

## Connections

- App entry → API shell: boots · Application bootstrap initializes the NestJS module graph
- App entry → Cross-cutting: configures · Global interceptors and exception handling are registered at startup
- API shell → Auth: includes · Authentication and authorization module
- API shell → Users: includes · User and admin account module
- API shell → Plots: includes · Core property lifecycle module
- API shell → NFTs: includes · NFT minting module
- API shell → Blockchain: includes · Blockchain integration module
- API shell → IPFS: includes · IPFS metadata module
- API shell → Storage: includes · File upload module
- API shell → Notifications: includes · Notification module
- API shell → Audit logs: includes · Audit logging module
- API shell → Transactions: includes · Blockchain transaction persistence
- Auth → Users: loads users · Authentication resolves and validates user identities
- Plots → PostgreSQL: persists · Property, document, and image records are stored in the database
- Users → PostgreSQL: persists · User and role records are stored in the database
- NFTs → IPFS: uploads metadata · NFT minting depends on IPFS metadata preparation
- NFTs → Blockchain: mints · NFT operations call the chain service for contract interaction
- Blockchain → EVM chain: writes on-chain · Smart contract calls and chain synchronization happen here
- IPFS → IPFS/Pinata: stores · Pinata-backed IPFS gateway is used for content storage
- Storage → IPFS/Pinata: uploads files · Uploaded documents and assets can be moved into the IPFS layer
- Client shell → Routes: uses · Client shell wires routing and page composition
- Client shell → Core services: uses · Shared services and application state power screens
- Routes → Route guards: protects · Routes are gated by auth and role checks
- Routes → Auth screens: exposes · Public entry routes for landing, login, and register
- Routes → User screens: exposes · User-facing property and profile workflows
- Routes → Admin screens: exposes · Admin review, management, and minting workflows
- Routes → Chain verify: exposes · Blockchain verification and wallet-related screens
- Core services → Auth: calls · Frontend authentication service consumes backend auth APIs
- Core services → Users: calls · User management services consume backend APIs
- Core services → Plots: calls · Property services consume backend plot APIs
- Core services → NFTs: calls · NFT services consume backend minting APIs
- Core services → Blockchain: calls · Web3-facing logic complements backend chain state
- Audit logs → Cross-cutting: observes · Audit logging is applied through central request instrumentation
- Transactions → Blockchain: records · Transaction metadata tracks blockchain operations
