Cahootz Monorepo

Cahootz is a platform for launching and operating community-owned economies. It brings together member onboarding, cooperative storefronts, payments, governance, proposal workflows, and treasury tooling in one monorepo.

The codebase currently includes web, mobile, API, database, smart contract, and shared service packages.

Documentation

• Getting Started - Set up the project locally.
• Cahootz Charter - Placeholder charter for the Cahootz era.
• Proposal Engine - How proposal submission, review, scoring, and voting are intended to work.
• Technical Roadmap - Product and engineering milestones.
• Organizational Roadmap - Operating model and rollout stages.
• Development Guide - Local workflows, debugging, and troubleshooting.
• Environment Files Guide - Environment variable layout.
• Testing Guide - Test commands and expectations.

What Cahootz Includes

• Member onboarding and co-op selection
• Public co-op pages and storefronts
• Product, cart, checkout, and payment flows
• Admin portals for members, stores, proposals, treasury, rewards, and settings
• Proposal submission, review, discussion, and voting workflows
• Smart contract deployment and configuration tools
• Mobile app flows for wallets, payments, stores, and member activity

Project Structure

cahootz/
├── apps/
│   ├── api/        # Express API service
│   ├── mobile/     # Expo mobile application
│   └── web/        # Next.js web application
├── documents/      # Product and operating documentation
├── packages/
│   ├── contracts/  # Smart contracts and deployment scripts
│   ├── db/         # Prisma schema, migrations, and seed scripts
│   ├── trpc/       # tRPC routers and backend services
│   ├── ui/         # Shared UI primitives
│   └── validators/ # Proposal and validation logic
├── scripts/        # Repo-level utilities
├── tooling/        # Shared lint, TypeScript, Tailwind, and Prettier config
└── turbo/          # Turborepo generators/configuration

Tech Stack

• Next.js 15, React 19, TypeScript, Tailwind CSS
• Expo and React Native
• Express, tRPC, Prisma, PostgreSQL, Zod
• Solidity, Hardhat, Base-compatible deployment scripts
• Turborepo and pnpm workspaces

Prerequisites

• Node.js >= 22.14.0
• pnpm >= 10.11.1
• PostgreSQL
• Git

Quick Start

pnpm install
pnpm db:generate
pnpm db:push
pnpm dev

The default local services are:

• Web: http://localhost:3000
• API: http://localhost:3001

See Getting Started for the fuller setup path.

Common Commands

pnpm dev              # Start development services
pnpm build            # Build packages and apps
pnpm lint             # Run linting
pnpm typecheck        # Run TypeScript checks
pnpm test             # Run tests
pnpm db:generate      # Generate Prisma client
pnpm db:push          # Push schema to the local database
pnpm db:migrate       # Run database migrations
pnpm db:studio        # Open Prisma Studio

Testing Newsletter Agents In Dev

Newsletter agents do not have a normal admin UI. In development, run them through the API-only test endpoint:

POST http://localhost:3001/dev/newsletter-agent/run

Run the Article Writer Agent:

curl -s -X POST http://localhost:3001/dev/newsletter-agent/run \
  -H "Content-Type: application/json" \
  -d '{
    "coopId": "soulaan",
    "agentId": "article-writer",
    "walletAddress": "0xYOUR_ADMIN_WALLET"
  }' | jq

The Article Writer Agent runs the full article pipeline internally: Article Research Curator, Article Source Verifier, Article Angle Selector, Article Writer, and Article Editor/Quality Gate. It returns fewer drafts by design; createdCount: 0 is valid when no source can support a specific, source-backed, goal-relevant article.

Refresh research first, then run the Article Writer Agent:

curl -s -X POST http://localhost:3001/dev/newsletter-agent/run \
  -H "Content-Type: application/json" \
  -d '{
    "coopId": "soulaan",
    "agentId": "article-writer",
    "walletAddress": "0xYOUR_ADMIN_WALLET",
    "refreshResearch": true,
    "sources": [
      { "url": "https://example.org/community-news" },
      { "url": "https://example.org/events" }
    ]
  }' | jq

Charter Compliance Check

The automated Charter Compliance Check is disabled for now while Cahootz documentation and governance language are being reset. The placeholder Cahootz charter lives at documents/cahootz-charter.md.

Contributing

1. Create a feature branch.
2. Make scoped changes in the relevant app or package.
3. Run the checks that match the risk of the change.
4. Update docs when behavior, setup, or operations change.
5. Open a pull request with clear testing notes.

License

This project is licensed under the MIT License. See LICENSE.