> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.adid.dev/llms.txt.
> For full documentation content, see https://docs.adid.dev/llms-full.txt.

# Local Development Setup

Set up a local development environment for IDA with all services running natively.

## Prerequisites

| Tool       | Version | Installation                                                      |
| ---------- | ------- | ----------------------------------------------------------------- |
| Go         | 1.22+   | `brew install go`                                                 |
| Rust       | 1.76+   | `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh` |
| Node.js    | 20 LTS  | `brew install node@20`                                            |
| PostgreSQL | 16+     | `brew install postgresql@16`                                      |
| Redis      | 7+      | `brew install redis`                                              |
| NATS       | 2.10+   | `brew install nats-server`                                        |
| Solidity   | 0.8.24+ | Via foundry: `curl -L https://foundry.paradigm.xyz \| bash`       |
| IPFS       | 0.27+   | `brew install ipfs`                                               |

## Repository Structure

```
ida/
  packages/
    api/            # Go/Rust backend services
      cmd/          # Service entrypoints
      internal/     # Internal packages
      pkg/          # Public libraries
    blockchain/     # Smart contracts
      contracts/    # Solidity source
      scripts/      # Deployment scripts
      test/         # Contract tests
    portal/         # React web portal
      src/
    wallet/         # Mobile wallet
  deployments/      # Docker, K8s manifests
  docs/             # This documentation
```

## 1. Clone and Install Dependencies

```bash
git clone https://github.com/infinia/ida.git
cd ida

# Install all workspace dependencies
make install
```

The `make install` command runs:

```makefile
install:
	cd packages/api && go mod download
	cd packages/blockchain && forge install
	cd packages/portal && npm install
```

## 2. Start Infrastructure Services

Start PostgreSQL, Redis, and NATS locally:

```bash
# Start PostgreSQL
brew services start postgresql@16
createdb ida_dev

# Start Redis
brew services start redis

# Start NATS
nats-server -D &

# Start IPFS daemon
ipfs init  # first time only
ipfs daemon &
```

## 3. Start ADI Local Devnet

Run a 2-node ADI blockchain for local development:

```bash
cd packages/blockchain
make devnet
```

This starts two ADI nodes on ports 30303 and 30304 with pre-funded accounts for testing.

## 4. Deploy Smart Contracts

Deploy the four core smart contracts to the local devnet:

```bash
cd packages/blockchain
forge script scripts/Deploy.s.sol --rpc-url http://localhost:30303 --broadcast
```

Output:

```
Deploying DID Registry...         deployed at 0x5FbDB2315678afecb367f032d93F642f64180aa3
Deploying Schema Registry...      deployed at 0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512
Deploying Revocation Registry...  deployed at 0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0
Deploying Agent Trust Registry... deployed at 0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9
```

Record these addresses in your `.env` file.

## 5. Configure Environment

Create a `.env` file in the project root:

```bash
cp .env.example .env
```

```env
# Database
DATABASE_URL=postgres://localhost:5432/ida_dev?sslmode=disable
REDIS_URL=redis://localhost:6379

# ADI Blockchain
ADI_RPC_URL=http://localhost:30303
ADI_CHAIN_ID=1337

# Smart Contract Addresses
DID_REGISTRY_ADDRESS=0x5FbDB2315678afecb367f032d93F642f64180aa3
SCHEMA_REGISTRY_ADDRESS=0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512
REVOCATION_REGISTRY_ADDRESS=0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0
AGENT_TRUST_REGISTRY_ADDRESS=0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9

# NATS
NATS_URL=nats://localhost:4222

# IPFS
IPFS_API_URL=http://localhost:5001

# API
API_PORT=8080
RESOLVER_PORT=8081
LOG_LEVEL=debug
```

## 6. Run Database Migrations

```bash
cd packages/api
make migrate-up
```

## 7. Start the API Server

```bash
cd packages/api
make run
```

The API will be available at `http://localhost:8080`.

## 8. Start the Web Portal

```bash
cd packages/portal
npm run dev
```

The portal will be available at `http://localhost:5173`.

## 9. Run Tests

```bash
# Smart contract tests
cd packages/blockchain && forge test -vvv

# API unit tests
cd packages/api && go test ./...

# API integration tests (requires running services)
cd packages/api && go test -tags=integration ./...

# Portal tests
cd packages/portal && npm test
```

## 10. Useful Make Commands

| Command                 | Description                      |
| ----------------------- | -------------------------------- |
| `make install`          | Install all dependencies         |
| `make dev`              | Start all services in dev mode   |
| `make test`             | Run all tests                    |
| `make lint`             | Run linters across all packages  |
| `make build`            | Build all packages               |
| `make docker-build`     | Build Docker images              |
| `make migrate-up`       | Run database migrations          |
| `make migrate-down`     | Rollback database migrations     |
| `make deploy-contracts` | Deploy smart contracts to devnet |
| `make clean`            | Clean build artifacts            |

## IDE Setup

### VS Code Extensions

* Go (golang.go)
* rust-analyzer
* ESLint
* Tailwind CSS IntelliSense
* Solidity (JuanBlanco.solidity)
* Prettier

### Recommended Settings

```json
{
  "editor.formatOnSave": true,
  "go.lintTool": "golangci-lint",
  "rust-analyzer.cargo.allTargets": true,
  "tailwindCSS.experimental.classRegex": [
    ["clsx\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
  ]
}
```

## Troubleshooting

| Issue                      | Solution                                                    |
| -------------------------- | ----------------------------------------------------------- |
| Port 8080 in use           | `lsof -i :8080` and kill the process                        |
| Database connection failed | Verify PostgreSQL is running: `pg_isready`                  |
| Contract deployment fails  | Ensure ADI devnet is running: `curl http://localhost:30303` |
| IPFS connection refused    | Start the daemon: `ipfs daemon &`                           |
| Redis connection refused   | Start Redis: `brew services start redis`                    |