Architecture overview

Scaffold-EVVM is a monorepo with three first-class workspaces and a top-level CLI that ties them together:

scaffold-evvm/
├── cli/                # Interactive TypeScript wizard (the "front door")
├── services/           # Drop your custom .sol services here
├── packages/
│   ├── foundry/        # Foundry contracts + deploy scripts
│   ├── hardhat/        # Hardhat package (compiles via forge)
│   └── nextjs/         # The frontend you interact with
├── input/              # Generated deployment input (Inputs.*.sol, address.json)
└── deployments/        # Generated deployment summaries

How the pieces fit together

┌──────────────────┐
│  npm run wizard  │  cli/index.ts
└────────┬─────────┘
         │
         ▼
┌──────────────────────────────────────────────────────┐
│  1. Pick framework (foundry|hardhat) + source        │
│  2. Generate input/Inputs.*.sol                      │
│  3. anvil --port 8545                                │
│  4. forge build --via-ir                             │
│  5. forge script Deploy.testnet.s.sol --broadcast    │
│  6. Write addresses → packages/nextjs/.env           │
│  7. (optional) Compile + deploy services/            │
│  8. next dev (port 3000)                             │
└──────────────────────────────────────────────────────┘

What runs where

Process	Port	Source
Local chain (Anvil/Hardhat)	8545	packages/foundry or packages/hardhat
Frontend (Next.js dev)	3000	packages/nextjs

Configuration files

File	Purpose
scaffold.config.json	Records the framework and contract source you chose. Used by re-runs of cli init to skip prompts.
input/Inputs.testnet.sol	Generated Solidity that feeds parameters into the deploy script.
input/address.json	The three admin addresses (admin, golden fisher, activator) the wizard asked you for.
packages/nextjs/.env	Generated by the wizard with NEXT_PUBLIC_* addresses.
deployments/customcontracts.json	Address + ABI registry of every service deployed from services/.
packages/nextjs/public/customservices.json	Same data, copied into public/ so the frontend can fetch it.

What the frontend does

Three things, in order of how often you'll touch them:

1. Signature constructors — Forms that build EIP-191 signatures for every EVVM operation (pay, stake, register, swap, etc.) and submit them via viem/wagmi. The signature shapes themselves come from the evvm-js SDK — the same typed client any external app would use.
2. EVVMScan — A self-contained block explorer at /evvmscan.
3. Custom services UI — Auto-generated read/write/event panels at /services/<name> for any contract you've dropped under services/.

Read the EVVM Signature Structures Overview next if you want to understand why every transaction needs two signatures.