DEVELOPER_SETUP.md

CeloHT Developer Setup

Version: 1.0 Project: CeloHT Environment: Linux / macOS / Windows Primary Stack: Next.js, React, TypeScript, Node.js, PostgreSQL, Celo

---

1. Purpose

This guide explains how developers can prepare a local environment for contributing to CeloHT projects.

The goal is to provide a predictable development workflow from repository setup to local testing.

---

2. Development Architecture

Developer
   │
   ▼
GitHub Repository
   │
   ▼
Local Development Environment
   │
   ├── Frontend
   ├── Backend / API
   ├── Database
   └── Blockchain Development Tools
   │
   ▼
Tests
   │
   ▼
Pull Request
   │
   ▼
CI/CD

---

3. Recommended Requirements

Developers should have:

• Git
• Node.js
• npm or another supported package manager
• A modern browser
• Code editor
• GitHub account
• Celo-compatible wallet for blockchain testing where required

For specific repositories, always follow the repository's own README.md.

---

4. Clone a Repository

Example:

git clone <REPOSITORY_URL>
cd <REPOSITORY_DIRECTORY>

Do not commit directly to the production branch unless repository policy explicitly permits it.

---

5. Install Dependencies

For a Node.js project:

npm install

Use the package manager and lockfile defined by the repository.

Do not randomly replace package managers because this can create dependency inconsistencies.

---

6. Environment Variables

Projects may require environment variables.

Example:

DATABASE_URL=
NEXT_PUBLIC_CELO_NETWORK=
NEXT_PUBLIC_RPC_URL=
NEXT_PUBLIC_CONTRACT_ADDRESS=

Environment files containing secrets must not be committed.

Use:

.env.local

for local-only configuration where supported.

---

7. Environment Separation

CeloHT environments should conceptually remain separate:

Development
     │
     ▼
Testing
     │
     ▼
Staging
     │
     ▼
Production

Production credentials must never be used for ordinary local development.

---

8. Run the Development Server

Typical Next.js command:

npm run dev

The repository README should specify the exact local URL.

---

9. Build the Application

npm run build

A successful development server does not guarantee that the production build will succeed.

Both should be tested before merging significant changes.

---

10. Run Tests

Typical command:

npm test

If the repository defines additional test commands, use those commands as documented.

---

11. Linting

Typical command:

npm run lint

Lint errors should normally be fixed before opening a pull request.

---

12. Formatting

If the repository uses Prettier:

npm run format

Formatting should remain consistent across the project.

---

13. Type Checking

For TypeScript projects:

npx tsc --noEmit

Type errors should be resolved before merging.

---

14. Database Development

Database-dependent repositories should document:

• Database provider
• Local setup
• Migration commands
• Seed commands
• Reset procedure

Never connect a local development environment to a production database unless explicitly authorized.

---

15. Blockchain Development

Blockchain-enabled repositories should document:

• Network
• Chain ID
• RPC configuration
• Contract addresses
• ABI source
• Wallet requirements
• Testnet procedure

Developers should use testnet or local environments before interacting with production contracts.

---

16. Wallet Development

For wallet-enabled applications:

1. Connect a test wallet.
2. Confirm the network.
3. Confirm the wallet address.
4. Confirm the requested transaction.
5. Test transaction failure states.
6. Verify the resulting transaction on the blockchain.

Never use a wallet containing important funds for experimental development.

---

17. Repository Structure

A typical CeloHT application may resemble:

project/
├── app/
├── components/
├── lib/
├── services/
├── contracts/
├── public/
├── tests/
├── docs/
├── scripts/
├── .github/
├── package.json
└── README.md

Actual structure depends on the repository.

---

18. Git Workflow

Recommended workflow:

main
 │
 ├── feature/*
 ├── fix/*
 └── docs/*

Create a branch before making changes:

git checkout -b feature/my-feature

---

19. Commit Messages

Use clear commit messages.

Examples:

feat: add agent dashboard
fix: correct transaction status
docs: update architecture guide
test: add wallet integration tests
refactor: simplify blockchain service

---

20. Pull Requests

A pull request should explain:

• What changed
• Why it changed
• How it was tested
• Any known limitations
• Any security implications

---

21. Security Rules

Developers must never commit:

• Private keys
• Seed phrases
• Passwords
• API secrets
• Database credentials
• Production credentials

If a secret is accidentally committed, treat it as compromised and rotate it immediately.

---

22. Local Verification Checklist

Before opening a PR:

[ ] Dependencies installed
[ ] Application runs
[ ] Tests pass
[ ] Lint passes
[ ] Type check passes
[ ] Production build succeeds
[ ] No secrets committed
[ ] Documentation updated

---

23. Troubleshooting

When something fails:

1. Read the complete error.
2. Check the repository README.
3. Check environment variables.
4. Check dependency versions.
5. Check logs.
6. Reproduce the issue.
7. Search existing GitHub issues.
8. Document the fix when appropriate.

Avoid repeatedly reinstalling dependencies without understanding the failure.

---

24. Developer Principle

CeloHT development follows:

Build reproducibly. Test locally. Review carefully. Deploy deliberately.

---

Status

Document: Developer Setup Version: 1.0 Project: CeloHT