# bijoy26/crypto-beacon architecture

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

- Interactive diagram: https://gitdiagram.com/bijoy26/crypto-beacon
- Repository: https://github.com/bijoy26/crypto-beacon

## Overview

1. **Repository purpose**
   - This is a Truffle-based proof-of-concept for a decentralized community platform called **CryptoBeacon**.
   - The repo is primarily the **blockchain application layer**: smart contracts, deployment scripts, and local test/development setup. The README also describes a planned front end and IPFS integration, but those pieces are not present in the file tree yet.

2. **Core runtime boundary**
   - The main execution boundary is the **Ethereum-compatible network**: local **Ganache** for development and **Polygon Mumbai testnet** for deployment.
   - Users interact with the system through a wallet/Web3 client, which sends transactions to the deployed contract rather than a traditional server backend.

3. **Smart contract subsystem**
   - The `contracts/` directory is the on-chain business logic layer.
   - Based on the README, the contract likely supports the platform’s core actions: publishing community updates, reading updates, and upvoting posts to establish trust.
   - This is the authoritative state store for platform data that must be transparent and tamper-resistant.

4. **Deployment pipeline**
   - The `migrations/` folder contains Truffle migration scripts:
     - `1_initial_migration.js` sets up Truffle’s migration bookkeeping.
     - `2_deploy_contracts.js` deploys the application contract(s).
   - This is the repo’s deployment boundary between source code and a live blockchain network.

5. **Local development and testing**
   - `truffle-config.js` defines network/compiler settings and is the key configuration file for running against local or remote chains.
   - The `test/` folder is present but mostly empty, so automated contract testing is only minimally scaffolded in this snapshot.
   - The README indicates local development was done with **Ganache** and Truffle.

6. **Frontend / client boundary**
   - The README describes a front end built with HTML/CSS/Bootstrap/JavaScript and Web3.js, but those source files are not in the tree.
   - Architecturally, the intended client would sit outside the blockchain and act as a thin presentation/transaction layer: connect wallet, read contract state, submit updates/upvotes.

7. **External storage plan**
   - The README calls out **IPFS** as a distributed storage layer to complement blockchain storage.
   - The intended architecture is likely: large or user-generated content stored off-chain in IPFS, with only references/hashes and metadata committed on-chain.
   - That integration is listed as planned, not yet implemented in this repo snapshot.

8. **Network and deployment targets**
   - The project is designed around **Polygon**, specifically noted as deployed to **Polygon Mumbai Testnet**.
   - This means the runtime is not a centralized server but a public blockchain network with contract addresses and transaction history visible externally.

9. **Assets and documentation**
   - `assets/` contains banners and system architecture imagery used for project presentation, not runtime behavior.
   - `README.md` and `changelog.md` provide the product narrative and progress status; they are important for understanding intended architecture but do not define executable paths.

10. **What is actually implemented vs. planned**
   - Implemented in this repo: contract code, deployment scripts, Truffle configuration, and the scaffolding for tests.
   - Planned but not present: a fully wired Web3 front end, IPFS integration, and production frontend deployment.
   - So the current architecture diagram should emphasize a **smart-contract-centric dApp foundation** with future client and storage layers still pending.

11. **Suggested diagram boundaries**
   - Show three major zones: **Client/Wallet**, **Blockchain (Truffle-deployed Solidity contracts on Polygon/Ganache)**, and **Distributed Storage (IPFS, planned)**.
   - The current repo mostly occupies the middle zone plus deployment tooling; the client and storage zones are architectural targets rather than completed modules.

Main entry points: [`contracts`](https://github.com/bijoy26/crypto-beacon/tree/master/contracts) (Contracts), [`truffle-config.js`](https://github.com/bijoy26/crypto-beacon/blob/master/truffle-config.js) (Truffle cfg), [`README.md`](https://github.com/bijoy26/crypto-beacon/blob/master/README.md) (README), [`migrations`](https://github.com/bijoy26/crypto-beacon/tree/master/migrations) (Migrations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client boundary"]
  node_wallet(("Wallet<br/>web3 client"))
  node_web_ui["Web UI<br/>planned frontend"]
end

subgraph group_chain["Blockchain app"]
  node_contracts{{"Contracts<br/>solidity"}}
  node_beacon_contract{{"Beacon app<br/>dapp contract"}}
  node_migrations["Migrations<br/>deploy scripts"]
  node_initial_migration["Init mig<br/>migrate script"]
  node_deploy_contracts["Deploy app<br/>migrate script"]
  node_truffle_config["Truffle cfg<br/>network config<br/>[truffle-config.js]"]
  node_tests["Tests<br/>scaffold"]
end

subgraph group_runtime["Chain runtime"]
  node_ganache[("Ganache<br/>local chain")]
  node_polygon_mumbai[("Mumbai<br/>testnet")]
end

subgraph group_storage["External storage"]
  node_ipfs[("IPFS<br/>planned storage")]
end

subgraph group_meta["Project materials"]
  node_readme["README<br/>docs<br/>[README.md]"]
  node_changelog["Changelog<br/>docs<br/>[changelog.md]"]
  node_assets["Assets"]
  node_manifest["Package<br/>npm manifest<br/>[package.json]"]
end

node_web_ui -->|"connect"| node_wallet
node_wallet -->|"submit tx"| node_contracts
node_web_ui -->|"read state"| node_contracts
node_migrations -->|"deploy"| node_contracts
node_initial_migration -->|"part of"| node_migrations
node_deploy_contracts -->|"part of"| node_migrations
node_truffle_config -->|"targets"| node_ganache
node_truffle_config -->|"targets"| node_polygon_mumbai
node_contracts -->|"runs on"| node_ganache
node_contracts -->|"deployed on"| node_polygon_mumbai
node_tests -->|"verify"| node_contracts
node_contracts -.->|"references"| node_ipfs
node_web_ui -.->|"planned access"| node_ipfs
node_readme -->|"describes"| node_contracts
node_readme -->|"plans"| node_ipfs
node_assets -->|"supports"| node_readme
node_manifest -->|"drives"| node_truffle_config

click node_contracts "https://github.com/bijoy26/crypto-beacon/tree/master/contracts"
click node_beacon_contract "https://github.com/bijoy26/crypto-beacon/tree/master/contracts"
click node_migrations "https://github.com/bijoy26/crypto-beacon/tree/master/migrations"
click node_initial_migration "https://github.com/bijoy26/crypto-beacon/blob/master/migrations/1_initial_migration.js"
click node_deploy_contracts "https://github.com/bijoy26/crypto-beacon/blob/master/migrations/2_deploy_contracts.js"
click node_truffle_config "https://github.com/bijoy26/crypto-beacon/blob/master/truffle-config.js"
click node_tests "https://github.com/bijoy26/crypto-beacon/tree/master/test"
click node_readme "https://github.com/bijoy26/crypto-beacon/blob/master/README.md"
click node_changelog "https://github.com/bijoy26/crypto-beacon/blob/master/changelog.md"
click node_assets "https://github.com/bijoy26/crypto-beacon/tree/master/assets"
click node_manifest "https://github.com/bijoy26/crypto-beacon/blob/master/package.json"

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_wallet,node_web_ui toneBlue
class node_contracts,node_beacon_contract,node_migrations,node_initial_migration,node_deploy_contracts,node_truffle_config,node_tests toneAmber
class node_ganache,node_polygon_mumbai toneMint
class node_ipfs toneRose
class node_readme,node_changelog,node_assets,node_manifest toneIndigo
```

## Components

### Client boundary

User-facing Web3 presentation and wallet interaction, currently planned rather than implemented in the tree.

- **Wallet**: web3 client · User wallet and transaction signer that initiates on-chain actions.
- **Web UI**: planned frontend · Planned HTML/CSS/Bootstrap/Web3.js presentation layer described in the README.

### Blockchain app

Truffle-managed smart contracts and deployment tooling that define the current executable core.

- [Contracts](https://github.com/bijoy26/crypto-beacon/tree/master/contracts): solidity · Authoritative on-chain business logic for community updates and trust signals. · `contracts`
- [Beacon app](https://github.com/bijoy26/crypto-beacon/tree/master/contracts): dapp contract · Representative application contract deployed by the migration flow. · `contracts`
- [Migrations](https://github.com/bijoy26/crypto-beacon/tree/master/migrations): deploy scripts · Truffle deployment scripts that initialize bookkeeping and deploy the application contract(s). · `migrations`
- [Init mig](https://github.com/bijoy26/crypto-beacon/blob/master/migrations/1_initial_migration.js): migrate script · Sets up Truffle's migration bookkeeping. · `migrations/1_initial_migration.js`
- [Deploy app](https://github.com/bijoy26/crypto-beacon/blob/master/migrations/2_deploy_contracts.js): migrate script · Deploys the application contract(s) to the target network. · `migrations/2_deploy_contracts.js`
- [Truffle cfg](https://github.com/bijoy26/crypto-beacon/blob/master/truffle-config.js): network config · Compiler and network settings for local and remote chain execution. · `truffle-config.js`
- [Tests](https://github.com/bijoy26/crypto-beacon/tree/master/test): scaffold · Minimal contract test scaffold present in the repository. · `test`

### Chain runtime

Ethereum-compatible networks used for local development and deployment targets.

- **Ganache**: local chain · Local Ethereum-compatible development chain used during contract iteration.
- **Mumbai**: testnet · Polygon Mumbai test network used as the public deployment target.

### External storage

Planned off-chain storage layer for larger content and references.

- **IPFS**: planned storage · Planned distributed storage layer for content too large or suitable for off-chain storage.

### Project materials

Documentation and presentation assets that explain the system but do not affect runtime behavior.

- [README](https://github.com/bijoy26/crypto-beacon/blob/master/README.md): docs · Primary narrative for the project goals, architecture, and planned integrations. · `README.md`
- [Changelog](https://github.com/bijoy26/crypto-beacon/blob/master/changelog.md): docs · Progress and release notes for the project snapshot. · `changelog.md`
- [Assets](https://github.com/bijoy26/crypto-beacon/tree/master/assets): presentation assets · Banners and architecture imagery used for project presentation. · `assets`
- [Package](https://github.com/bijoy26/crypto-beacon/blob/master/package.json): npm manifest · Dependency and script manifest for the Truffle-based project. · `package.json`

## Connections

- Web UI → Wallet: connect · The UI is expected to use a wallet for signing and account access.
- Wallet → Contracts: submit tx · Users interact with the platform by sending transactions to contract methods.
- Web UI → Contracts: read state · The presentation layer reads public contract state through Web3.
- Migrations → Contracts: deploy · Migration scripts produce the on-chain application deployment.
- Init mig → Migrations: part of · Initial migration is one step in the deployment pipeline.
- Deploy app → Migrations: part of · Application deployment is the main migration step for the repo.
- Truffle cfg → Ganache: targets · Local chain settings point Truffle to the development network.
- Truffle cfg → Mumbai: targets · Network settings enable deployment to Polygon Mumbai.
- Contracts → Ganache: runs on · Contracts are developed and exercised against the local chain.
- Contracts → Mumbai: deployed on · The public runtime target for the application is Polygon Mumbai.
- Tests → Contracts: verify · The test scaffold is intended to validate contract behavior.
- Contracts → IPFS: references · Planned architecture stores large content off-chain and keeps hashes or pointers on-chain.
- Web UI → IPFS: planned access · The future client would fetch off-chain content through IPFS references.
- README → Contracts: describes · The README explains the contract-centric platform behavior.
- README → IPFS: plans · The README mentions IPFS as a planned storage layer.
- Assets → README: supports · Presentation assets support the project documentation and visuals.
- Package → Truffle cfg: drives · The package manifest anchors project scripts and dependencies used by Truffle.