Expand local development guide with troubleshooting, architecture overview, and contribution workflow

[DeFiVC]

Description

The file guides/local-development.md (337 lines) covers basic setup but has several issues:

1. Incorrect tool references: Uses prisma commands (lines 78, 81, 160) but the project uses Drizzle ORM (drizzle-kit)
2. Missing architecture overview: No diagram or explanation of how the 7 packages relate to each other
3. Incomplete environment variables: Several required vars are missing or have wrong defaults
4. No contribution workflow: No guidance on branches, PRs, commit conventions, or code review

What needs to be fixed/added

1. Fix Prisma references -> Drizzle

Replace all npx prisma commands with Drizzle equivalents:

# Database migrations (currently wrong — says "npx prisma migrate dev")
cd chainlearn-api
npx drizzle-kit generate    # Generate migration SQL
npx drizzle-kit migrate     # Run migrations
npx drizzle-kit studio      # Open Drizzle Studio (DB browser)

# Seed (currently wrong — says "npx prisma db seed")
npm run db:seed             # Uses tsx src/database/seed.ts

For the indexer, the migration command is:

cd chainlearn-indexer
npm run migrate             # Uses tsx src/database/migrate.ts

2. Add architecture overview section

Add after "Prerequisites":

## Architecture Overview

ChainLearn is a multi-repo monorepo with 7 independent packages:

+---------------+     +---------------+     +---------------+
|   Frontend    |---->|   API Server  |---->|  AI Service   |
|   (Next.js)   |<----|   (Fastify)   |<----|  (FastAPI)    |
+-------+-------+     +-------+-------+     +---------------+
        |                     |
        v                     v
+---------------+     +---------------+     +---------------+
|   Stellar     |     |  PostgreSQL   |     |   Indexer     |
|   Network     |     |  + Redis      |     |  (Fastify)    |
|  (Soroban)    |     +---------------+     +-------+-------+
+---------------+                                 |
                                          +-------v-------+
                                          |   Stellar     |
                                          |   Network     |
                                          +---------------+

| Package            | Stack                        | Port  |
|--------------------|------------------------------|-------|
| chainlearn-api     | Node, Fastify, TypeScript    | 3000  |
| chainlearn-frontend| Next.js 14, Tailwind         | 3000  |
| chainlearn-ai      | Python, FastAPI, Cohere       | 8000  |
| chainlearn-indexer | Node, Fastify, TypeScript     | 3100  |
| chainlearn-contracts| Rust, Soroban SDK           | N/A   |
| chainlearn-infra   | Terraform, Docker Compose     | N/A   |
| chainlearn-docs    | Markdown, OpenAPI             | N/A   |

3. Fix environment variables

The frontend .env example says VITE_API_URL (line 192) — this is a Vite convention. Next.js uses NEXT_PUBLIC_ prefix:

# Frontend (.env.local)
NEXT_PUBLIC_API_URL=http://localhost:3000
NEXT_PUBLIC_STELLAR_NETWORK=testnet

4. Add contribution workflow section

## Contribution Workflow

### Branch Naming
- `feature/description` — new features
- `fix/description` — bug fixes
- `test/description` — test additions
- `docs/description` — documentation changes

### Commit Messages
Follow Conventional Commits:
- `feat: add quiz generation endpoint`
- `fix: resolve enrollment count bug`
- `test: add E2E tests for credentials module`
- `docs: update local development guide`

### PR Process
1. Create a branch from `main`
2. Make changes with tests
3. Run lint + typecheck:
   - API: `npm run lint && npm run typecheck`
   - Frontend: `npm run lint`
   - AI: `ruff check src/ tests/`
   - Contracts: `cargo test`
4. Push and create PR
5. PR will trigger CI (lint, test, build)
6. Address review feedback
7. Squash and merge

### Code Style
- TypeScript: ESLint + Prettier (existing config)
- Python: Ruff (line length 100)
- Rust: `cargo fmt` + `cargo clippy`
- Commit messages: Conventional Commits

5. Add more troubleshooting entries

### "Module not found" errors in contracts

Ensure the WASM target is installed:
rustup target add wasm32-unknown-unknown

### Cohere API errors

Verify your API key is valid and has quota:
curl -H "Authorization: Bearer $COHERE_API_KEY" https://api.cohere.ai/v1/models

### Frontend can't connect to API

Check that NEXT_PUBLIC_API_URL is set in .env.local (not .env).
Next.js only exposes env vars with NEXT_PUBLIC_ prefix to the browser.

Files to change

• guides/local-development.md — expand with fixes and new sections

References

• Technical architecture: chainlearn-technical-architecture.md (947 lines)
• API package.json: uses Drizzle, not Prisma
• Frontend package.json: Next.js (not Vite)

[olufunsoolutayo]

I have experience with this type of issue. pls assign and will resolve swiftly.

[okeolaolatun23-glitch]

Experienced in backend development, APIs, and OOP, with a strong interest in building scalable and maintainable software systems.

[Menjay7]

Hi! I came across this issue and would love to work on it. I have experience with similar tasks and I'm confident I can investigate, implement a clean solution, and thoroughly test it before submitting a PR. If the issue is still open, I would appreciate it if you could assign it to me. Thank you!

[coredevdave-cmd]

Application

I'd like to take on this documentation improvement task.

I reviewed the requirements and identified the main gaps: outdated Prisma references, missing architecture documentation, incorrect frontend environment variable examples, lack of contribution workflow guidance, and incomplete troubleshooting coverage.

Planned Changes

• Replace all Prisma commands with the correct Drizzle ORM workflow (drizzle-kit generate, migrate, studio, and project-specific migration commands).
• Add an Architecture Overview section with package relationships, dependency flow, and package/port reference table.
• Correct frontend environment variable examples to use Next.js conventions (NEXT_PUBLIC_*).
• Add a Contribution Workflow section covering branch naming, Conventional Commits, PR process, and code style expectations.
• Expand troubleshooting documentation with contract build, Cohere API, and frontend connectivity issues.
• Cross-check all changes against the technical architecture documentation and package configurations to ensure accuracy.

Validation

• Verify all commands match current package scripts and tooling.
• Confirm environment variable examples align with Next.js behavior.
• Review the guide for consistency and onboarding usability.
• Ensure documentation remains easy to follow for new contributors.

This update will make the local development guide accurate, easier to onboard from, and aligned with the project's current architecture and tooling.