DevChama

DevChama is a local‑first, event‑sourced learning & collaboration platform for small developer investment groups ("chamas"). Members propose learning tracks, stake funds on sprints, submit work, peer‑review, earn points, and distribute pooled rewards.

Tech Stack

• React 19 + TypeScript
• Livestore (local-first sync & SQLite event materialization)
• Vite + Bun
• Cloudflare Worker sync backend (@livestore/sync-cf)
• PWA (service worker + manifest + installable icons)

Core Concepts

• Event Sourcing: Domain events (v1.*) are committed and materialized into SQLite tables.
• Local-first: Works offline; sync applies when connectivity returns.
• Voting: Sprint proposals require majority approval of 5-member chama.
• Scoring: Approvals (+10) / rejections (−5) influence leaderboard & rewards.
• Rewards: Top 3 eligible contributors split 50% / 30% / 20% of reward pool.

Domain Events (Key)

Event	Purpose
v1.UserCreated / v1.UserUpdated	Manage user identity & wallet balance
v1.ChamaCreated / v1.ChamaUpdated	Manage chama membership & fund balance
v1.TrackCreated	Learning track definition
v1.SprintCreated / v1.SprintUpdated	Sprint lifecycle (proposed → active → completed/rejected)
v1.SubmissionCreated	Code / PR submission
v1.ReviewCreated	Peer review decision
v1.SprintVoteCast	Governance voting (approve / reject)
v1.LeaderboardUpdated	Leaderboard row materialization
v1.RewardAssigned	Reward distribution record

Running Locally

# Clone & install
bun install

# (Optional) Run local sync worker (Cloudflare):
# wrangler dev (if configured)

# Start app (includes registering service worker)
export VITE_LIVESTORE_SYNC_URL='http://localhost:8787'
bun run dev

Visit: http://localhost:5173 (default Vite port)

Testing

bun run test

Uses Vitest; tests live in tests/ (scoring, submissions, reviews).

Building

bun run build

Outputs production bundle to dist/.

PWA

• public/manifest.json
• public/sw.js (versioned precache + runtime strategies, offline fallback)
• Icons: icon-192.svg, icon-512.svg

CI

GitHub Actions workflow: .github/workflows/ci.yml runs install, build, and tests on pushes & PRs.

Developer Onboarding

1. Install Bun (https://bun.sh)
2. Copy .env.example (if present) → .env, set VITE_LIVESTORE_SYNC_URL
3. Start local sync worker (or point to deployed URL)
4. Run bun run dev
5. Register or create a chama, propose a sprint after 5 members join.

Sprint Voting Flow

1. Member proposes sprint (status = proposed)
2. Members cast v1.SprintVoteCast events
3. When approvals >= majority (ceil(members/2)) and members == 5:
   • Chama fund decremented by stake
   • Sprint becomes active
4. Rejection majority marks sprint rejected

Reward Distribution

On sprint completion (FinalizeSprint):

1. Leaderboard recalculated
2. Top 3 with >0 points receive rewards (50/30/20)
3. v1.RewardAssigned events recorded

Offline Behavior

• Core shell & icons precached
• Runtime caching for static assets (stale-while-revalidate)
• Navigation fallback to / when offline

Next Improvements (Suggested)

• Add end-to-end tests (Playwright)
• Configurable voting thresholds
• Wallet transaction ledger table
• Enhanced access control & auth

License

Proprietary / Internal (adjust as needed)