How nipundineshan/blockchain-plot-management works
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: app.module.ts API shell · app.routes.ts Routes · services Core services · blockchain Blockchain
Components 24
Backend
NestJS API, domain modules, and server-side orchestration
- App entry · Starts the backend app, configures global concerns, and serves the built client
be/src/main.ts - API shell · Top-level NestJS module composing backend features
be/src/app.module.ts - Cross-cutting · Global exception handling, logging, transforms, and audit capture
be/src/common - Auth · Login, registration, JWT strategy, and role-based access control
be/src/auth - Users · User accounts plus admin and super-admin controllers
be/src/users - Plots · Core property lifecycle, documents, images, and plot records
be/src/plots - NFTs · NFT creation and mint orchestration for approved properties
be/src/nft - Blockchain · Chain interaction and synchronization services
be/src/blockchain - IPFS · Uploads metadata and asset references through Pinata-backed IPFS
be/src/ipfs - Storage · Handles user file and document upload traffic separate from chain writes
be/src/storage - Notifications · User and admin notifications around workflow events
be/src/notifications - Audit logs · Persisted audit trail for regulated property operations
be/src/audit-logs - Transactions · Stores blockchain transaction metadata and outcomes
be/src/transactions
Frontend
Angular client with role-based screens and shared services
- Client shell · Frontend application shell, configuration, and routing host
fe/src/app/app.component.ts - Routes · Role-segmented navigation and screen access
fe/src/app/app.routes.ts - Core services · Auth, plots, users, NFTs, app state, export, and Web3 services
fe/src/app/core/services - Route guards · Auth and role guards for user, admin, super-admin, and authority screens
fe/src/app/core/guards - User screens · Register, browse, track approvals, manage documents, and profile views
fe/src/app/user-dashboard - Admin screens · Property review, user management, verification, minting, and settings
fe/src/app/admin-dashboard - Auth screens · Landing, login, and registration entry points
fe/src/app/login - Chain verify · Client-side blockchain verification and wallet-related screens
fe/src/app/blockchain-verification
External
Databases, blockchain, and content infrastructure
- PostgreSQL · Primary persistent store behind the TypeORM-backed backend
- EVM chain · Blockchain where approved properties are minted as NFTs
- IPFS/Pinata · Off-chain metadata and file storage layer
Connections 34
- 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