Charisma DeFi Platform
A comprehensive monorepo for decentralized finance applications built on Stacks, featuring advanced trading tools, token infrastructure, and real-time data services.
Monorepo Structure
Charisma uses a modern monorepo architecture powered by Turborepo and pnpm workspaces. The codebase is organized for clarity, scalability, and developer velocity.
Directory Layout
/apps/ # Application entrypoints (Next.js, CLI, etc.)
/modules/ # Internal shared logic, adapters, business logic, types (not published)
/services/ # Deployable backend services (APIs, workers, daemons, etc.)
/packages/ # Public packages (SDKs, libraries, config, for external npm publishing)
/docs/ # Technical documentation and API references
/scripts/ # Utility scripts for development and automation
Directory Purpose
| Directory | Purpose | Publishes to npm? | Example Contents |
|---|
| apps/ | User-facing applications | No | simple-swap, dex-cache |
| modules/ | Internal shared logic/modules | No | db-adapter, types, core |
| services/ | Deployable backend services | No | user-api, party-service |
| packages/ | Public packages/libraries | Yes | blaze-sdk, dexterity |
Applications
- simple-swap: Main DEX interface with limit orders, DCA strategies, and advanced trading features
- pro-interface: Professional trading tools with charts and analytics
- dex-cache: Price discovery, liquidity analysis, and market data caching
- token-cache: Token metadata caching and validation service
- metadata: Token and contract metadata management
- charisma-party: Real-time data feeds powered by PartyKit
- blaze-signer: Experimental playground for transaction signing, verification, and intent management concepts
- contract-search: Smart contract discovery and analysis
- launchpad: Token creation and contract deployment tools
- meme-roulette: Gaming application with token mechanics
Internal Modules
- discovery: Environment/hostname discovery and validation
- (Add more as your codebase evolves)
Services
- (Add more as your backend grows)
Public Packages
- @repo/blaze-sdk: Stacks blockchain SDK for external developers
- @repo/tx-monitor-client: Transaction monitoring client
- @repo/tokens: Token metadata library and caching utilities
- @repo/ui: Shared UI component library
- @repo/eslint-config: ESLint configurations for external use
- @repo/typescript-config: TypeScript configurations for external use
Technology Stack
Frontend
- Framework: Next.js 15 with App Router
- Language: TypeScript (strict mode)
- Styling: Tailwind CSS
- UI Components: shadcn/ui with custom extensions
- Charts: Lightweight Charts for trading interfaces
- State Management: React Context
Backend & Data
- Database: Vercel KV (Redis-compatible key-value store)
- File Storage: Vercel Blob
- Real-time: PartyKit for WebSocket connections
- Blockchain: Stacks integration via Blaze SDK
- APIs: RESTful endpoints with Next.js API routes
Infrastructure
- Monorepo: Turborepo for build optimization and caching
- Package Manager: pnpm with workspaces
- Deployment: Vercel for all applications
- CI/CD: Automated builds and testing pipelines
Getting Started
Prerequisites
- Node.js 18+
- pnpm (recommended)
- Git
Installation
git clone <repository-url>
cd charisma
pnpm install
Environment Configuration
Copy and configure environment variables for each app/service as needed:
cp apps/simple-swap/.env.example apps/simple-swap/.env.local
cp apps/dex-cache/.env.example apps/dex-cache/.env.local
# ...repeat for other apps/services
Development
# Start all development servers
pnpm dev
# Or start specific applications/services
pnpm dev --filter=apps/simple-swap
pnpm dev --filter=services/party-service
Monorepo Commands
pnpm dev # Start all applications/services
pnpm build # Build all packages, modules, services, and apps
pnpm test # Run all tests
pnpm lint # Lint all packages
pnpm clean # Clean all build artifacts
# Add dependency to a specific workspace
pnpm add <pkg> --filter=modules/business-logic
Architecture
Directory Roles
- apps/: User-facing applications (web, CLI, etc.)
- modules/: Internal, reusable logic (business logic, adapters, types)
- services/: Deployable backend services (APIs, workers)
- packages/: Public, versioned packages for external use
Inter-App/Service Communication
- Prefer direct imports from
modules/ for internal logic sharing (type-safe, no HTTP overhead)
- Use HTTP/WebSocket APIs only for cross-service boundaries or external integrations
- Shared types/interfaces live in
modules/shared-types
Example Data Flow
Price Data Pipeline
- services/dex-cache: Fetches and processes market data
- Vercel KV: Caches processed price information
- services/party-service: Broadcasts real-time updates
- apps/simple-swap: Consumes data for trading interface
Token Information
- services/token-cache: Maintains metadata cache
- services/metadata: Enriches token information
- modules/shared-types: Provides typed interfaces
- All Apps/Services: Consume consistent token data
Development Workflow
Working with Multiple Apps/Services
# Terminal 1: Start shared services
pnpm dev --filter=services/token-cache --filter=services/party-service
# Terminal 2: Start main applications
pnpm dev --filter=apps/simple-swap --filter=apps/dex-cache
This is the beginning of the README. Read the rest at the original. Read the full README ↗
