# hafeefapc/events architecture

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

- Interactive diagram: https://gitdiagram.com/hafeefapc/events
- Repository: https://github.com/hafeefapc/events

## Overview

FreeEventMap lets people discover local free events and submit event listings to blockchain-backed storage. The main submission flow is map selection and event details, followed by a contract write through the Scaffold-ETH hooks and wallet transaction layer. The repository also includes event browsing, a block explorer, and contract-debugging UI. Event-browsing implementation was not sampled, so its internal data flow is left unspecified.

Main entry points: [`packages/nextjs/app/layout.tsx`](https://github.com/hafeefapc/events/blob/main/packages/nextjs/app/layout.tsx) (App shell), [`packages/nextjs/hooks/scaffold-eth/useScaffoldWriteContract.ts`](https://github.com/hafeefapc/events/blob/main/packages/nextjs/hooks/scaffold-eth/useScaffoldWriteContract.ts) (Contract writes), [`packages/nextjs/app/blockexplorer/_components/SearchBar.tsx`](https://github.com/hafeefapc/events/blob/main/packages/nextjs/app/blockexplorer/_components/SearchBar.tsx) (Address/hash search), [`packages/nextjs/app/markevents/page.tsx`](https://github.com/hafeefapc/events/blob/main/packages/nextjs/app/markevents/page.tsx) (Mark event)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_events["Event discovery"]
  node_mark["Mark event<br/>[page.tsx]"]
  node_browse["Browse events<br/>[page.tsx]"]
end

subgraph group_chain["Blockchain access"]
  node_read_hook["Contract reads"]
  node_write_hook["Contract writes"]
  node_transactor["Transaction handler<br/>[useTransactor.tsx]"]
  node_contract_info["Contract registry"]
  node_wagmi["Wallet and RPC config<br/>[wagmiConfig.tsx]"]
  node_event_contract["EventStorage contract"]
  node_debug["Contract debugger<br/>[page.tsx]"]
end

subgraph group_explorer["Chain inspection"]
  node_explorer_home["Block explorer<br/>[page.tsx]"]
  node_block_feed["Block feed<br/>[useFetchBlocks.ts]"]
  node_search["Address/hash search<br/>[SearchBar.tsx]"]
  node_address_page["Address details<br/>[page.tsx]"]
  node_tx_page["Transaction details<br/>[page.tsx]"]
end

subgraph group_app["Shared app shell"]
  node_shell["App shell<br/>[layout.tsx]"]
end

node_visitor(("Event seeker"))
node_map_service["Geocoding service"]
node_network[("Blockchain network")]
node_wallet(("Wallet user"))

node_visitor -->|"submits listing"| node_mark
node_mark -.->|"reverse geocodes"| node_map_service
node_mark -->|"writes listing"| node_write_hook
node_write_hook -->|"loads ABI and address"| node_contract_info
node_write_hook -->|"tracks transaction"| node_transactor
node_transactor -->|"gets wallet client"| node_wagmi
node_transactor -->|"waits for receipt"| node_network
node_write_hook -->|"submits contract write"| node_network
node_browse -->|"reads event data"| node_read_hook
node_read_hook -->|"loads ABI and address"| node_contract_info
node_read_hook -->|"reads contract"| node_network
node_visitor -->|"explores events"| node_browse
node_visitor -->|"inspects chain"| node_explorer_home
node_explorer_home -->|"loads blocks"| node_block_feed
node_block_feed -->|"fetches blocks and receipts"| node_network
node_explorer_home -->|"searches chain data"| node_search
node_search -->|"checks transaction hash"| node_network
node_search -->|"routes address"| node_address_page
node_search -->|"routes transaction"| node_tx_page
node_visitor -->|"inspects contracts"| node_debug
node_wallet -->|"connects wallet"| node_wagmi
node_shell -->|"hosts route"| node_mark
node_shell -->|"hosts route"| node_browse
node_shell -->|"hosts route"| node_explorer_home
node_shell -->|"hosts route"| node_debug

click node_mark "https://github.com/hafeefapc/events/blob/main/packages/nextjs/app/markevents/page.tsx"
click node_browse "https://github.com/hafeefapc/events/blob/main/packages/nextjs/app/viewevents/page.tsx"
click node_read_hook "https://github.com/hafeefapc/events/blob/main/packages/nextjs/hooks/scaffold-eth/useScaffoldReadContract.ts"
click node_write_hook "https://github.com/hafeefapc/events/blob/main/packages/nextjs/hooks/scaffold-eth/useScaffoldWriteContract.ts"
click node_transactor "https://github.com/hafeefapc/events/blob/main/packages/nextjs/hooks/scaffold-eth/useTransactor.tsx"
click node_contract_info "https://github.com/hafeefapc/events/blob/main/packages/nextjs/contracts/deployedContracts.ts"
click node_wagmi "https://github.com/hafeefapc/events/blob/main/packages/nextjs/services/web3/wagmiConfig.tsx"
click node_event_contract "https://github.com/hafeefapc/events/blob/main/packages/nextjs/contracts/deployedContracts.ts"
click node_explorer_home "https://github.com/hafeefapc/events/blob/main/packages/nextjs/app/blockexplorer/page.tsx"
click node_block_feed "https://github.com/hafeefapc/events/blob/main/packages/nextjs/hooks/scaffold-eth/useFetchBlocks.ts"
click node_search "https://github.com/hafeefapc/events/blob/main/packages/nextjs/app/blockexplorer/_components/SearchBar.tsx"
click node_address_page "https://github.com/hafeefapc/events/blob/main/packages/nextjs/app/blockexplorer/address/%5Baddress%5D/page.tsx"
click node_tx_page "https://github.com/hafeefapc/events/blob/main/packages/nextjs/app/blockexplorer/transaction/%5BtxHash%5D/page.tsx"
click node_debug "https://github.com/hafeefapc/events/blob/main/packages/nextjs/app/debug/page.tsx"
click node_shell "https://github.com/hafeefapc/events/blob/main/packages/nextjs/app/layout.tsx"

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_mark,node_browse,node_wallet toneBlue
class node_read_hook,node_write_hook,node_transactor,node_contract_info,node_wagmi,node_event_contract,node_debug,node_network toneAmber
class node_explorer_home,node_block_feed,node_search,node_address_page,node_tx_page toneMint
class node_shell toneRose
class node_visitor,node_map_service toneIndigo
```

## Components

### Event discovery

- [Mark event](https://github.com/hafeefapc/events/blob/main/packages/nextjs/app/markevents/page.tsx): `packages/nextjs/app/markevents/page.tsx`
- [Browse events](https://github.com/hafeefapc/events/blob/main/packages/nextjs/app/viewevents/page.tsx): `packages/nextjs/app/viewevents/page.tsx`

### Blockchain access

- [Contract reads](https://github.com/hafeefapc/events/blob/main/packages/nextjs/hooks/scaffold-eth/useScaffoldReadContract.ts): `packages/nextjs/hooks/scaffold-eth/useScaffoldReadContract.ts`
- [Contract writes](https://github.com/hafeefapc/events/blob/main/packages/nextjs/hooks/scaffold-eth/useScaffoldWriteContract.ts): `packages/nextjs/hooks/scaffold-eth/useScaffoldWriteContract.ts`
- [Transaction handler](https://github.com/hafeefapc/events/blob/main/packages/nextjs/hooks/scaffold-eth/useTransactor.tsx): `packages/nextjs/hooks/scaffold-eth/useTransactor.tsx`
- [Contract registry](https://github.com/hafeefapc/events/blob/main/packages/nextjs/contracts/deployedContracts.ts): `packages/nextjs/contracts/deployedContracts.ts`
- [Wallet and RPC config](https://github.com/hafeefapc/events/blob/main/packages/nextjs/services/web3/wagmiConfig.tsx): `packages/nextjs/services/web3/wagmiConfig.tsx`
- [EventStorage contract](https://github.com/hafeefapc/events/blob/main/packages/nextjs/contracts/deployedContracts.ts): `packages/nextjs/contracts/deployedContracts.ts`
- [Contract debugger](https://github.com/hafeefapc/events/blob/main/packages/nextjs/app/debug/page.tsx): `packages/nextjs/app/debug/page.tsx`

### Chain inspection

- [Block explorer](https://github.com/hafeefapc/events/blob/main/packages/nextjs/app/blockexplorer/page.tsx): `packages/nextjs/app/blockexplorer/page.tsx`
- [Block feed](https://github.com/hafeefapc/events/blob/main/packages/nextjs/hooks/scaffold-eth/useFetchBlocks.ts): `packages/nextjs/hooks/scaffold-eth/useFetchBlocks.ts`
- [Address/hash search](https://github.com/hafeefapc/events/blob/main/packages/nextjs/app/blockexplorer/_components/SearchBar.tsx): `packages/nextjs/app/blockexplorer/_components/SearchBar.tsx`
- [Address details](https://github.com/hafeefapc/events/blob/main/packages/nextjs/app/blockexplorer/address/%5Baddress%5D/page.tsx): `packages/nextjs/app/blockexplorer/address/[address]/page.tsx`
- [Transaction details](https://github.com/hafeefapc/events/blob/main/packages/nextjs/app/blockexplorer/transaction/%5BtxHash%5D/page.tsx): `packages/nextjs/app/blockexplorer/transaction/[txHash]/page.tsx`

### Shared app shell

- [App shell](https://github.com/hafeefapc/events/blob/main/packages/nextjs/app/layout.tsx): `packages/nextjs/app/layout.tsx`

### Other components

- **Event seeker**
- **Geocoding service**
- **Blockchain network**
- **Wallet user**

## Connections

- Event seeker → Mark event: submits listing
- Mark event → Geocoding service: reverse geocodes
- Mark event → Contract writes: writes listing
- Contract writes → Contract registry: loads ABI and address
- Contract writes → Transaction handler: tracks transaction
- Transaction handler → Wallet and RPC config: gets wallet client
- Transaction handler → Blockchain network: waits for receipt
- Contract writes → Blockchain network: submits contract write
- Browse events → Contract reads: reads event data
- Contract reads → Contract registry: loads ABI and address
- Contract reads → Blockchain network: reads contract
- Event seeker → Browse events: explores events
- Event seeker → Block explorer: inspects chain
- Block explorer → Block feed: loads blocks
- Block feed → Blockchain network: fetches blocks and receipts
- Block explorer → Address/hash search: searches chain data
- Address/hash search → Blockchain network: checks transaction hash
- Address/hash search → Address details: routes address
- Address/hash search → Transaction details: routes transaction
- Event seeker → Contract debugger: inspects contracts
- Wallet user → Wallet and RPC config: connects wallet
- App shell → Mark event: hosts route
- App shell → Browse events: hosts route
- App shell → Block explorer: hosts route
- App shell → Contract debugger: hosts route