Aligned Mini App

A multi-tenant decentralized social curation system for Ethereum-aligned communities. This Next.js 15 application enables communities to manage member voting on potential new members through a subgroup assignment system, built as a Farcaster mini-app.

Overview

The Aligned Mini App provides:

• Multi-Tenant Architecture: Each community/group operates independently with isolated data
• Member Curation: Democratic voting system for adding/removing community members
• Subgroup Management: Organized voting through subgroup assignments
• Farcaster Integration: Built as a mini-app using Frame SDK
• External API: Integrates with voting-services-api for all data operations

Quick Start

Prerequisites

• Node.js 18+
• pnpm package manager
• Access to voting-services-api backend

Installation

# Clone the repository
git clone <repository-url>
cd aligned-mini-app

# Install dependencies
pnpm install

# Install Playwright for testing
pnpm run test:install

Environment Setup

Create a .env.local file with required variables:

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:4000

# Farcaster Configuration
NEYNAR_API_KEY=your_neynar_api_key

# Frame SDK environment variables
# (Additional Frame SDK variables as needed)

Development

# Start development server
pnpm dev

# Open http://localhost:3000

Build & Deploy

# Build for production
pnpm build

# Start production server
pnpm start

Development Commands

• pnpm dev - Start development server
• pnpm build - Build the application
• pnpm lint - Run ESLint and format code
• pnpm lint:fix - Fix ESLint issues only
• pnpm format - Format code with Prettier
• pnpm format:check - Check code formatting
• pnpm typecheck - Run TypeScript type checking
• pnpm start - Start production server

Testing

# Run all tests
pnpm test

# Run tests with UI
pnpm test:ui

# Show test report
pnpm test:report

# Debug tests
pnpm test:debug

See tests/README.md for comprehensive testing documentation.

Architecture

Tech Stack

• Framework: Next.js 15 with App Router
• Language: TypeScript
• Styling: Tailwind CSS + shadcn/ui components
• State Management: TanStack Query
• Authentication: Frame SDK
• Blockchain: viem + wagmi for wallet interactions
• Testing: Playwright with comprehensive mocking system

Key Features

• Multi-Tenant Routing: /groups/[groupId]/ URL structure
• Server-Side Rendering: Data prefetching in server components
• External API Integration: All data operations via voting-services-api
• Mobile-First Design: Optimized for mobile Farcaster experience
• Comprehensive Testing: Playwright tests with Frame SDK mocking

Project Structure

app/
├── groups/[groupId]/          # Group-scoped routes
│   ├── page.tsx              # Group dashboard
│   ├── members/              # Member management
│   ├── proposals/            # Proposal management
│   ├── settings/             # Group configuration
│   └── ...
├── components/               # Reusable UI components
├── lib/                      # Utilities and types
└── tests/                    # Playwright test suite

Contributing

Code Style

• ESLint + Prettier for consistent formatting
• TypeScript strict mode
• Prefer kebab-case for file names
• Follow existing component patterns

Development Workflow

1. Create feature branch from develop
2. Implement changes with tests
3. Run pnpm lint and pnpm typecheck
4. Submit pull request to develop

Testing Guidelines

• Write Playwright tests for new features
• Use the comprehensive mocking system for Frame SDK
• Ensure tests cover authentication flows
• See tests/README.md for detailed guidance

External Dependencies

voting-services-api

This app requires the companion voting-services-api backend:

• Repository: ../voting-services-api (sibling directory)
• Purpose: All data operations, authentication validation, multi-tenant data isolation
• API Base: Configured via NEXT_PUBLIC_API_URL

Frame SDK

• Purpose: Farcaster mini-app integration and authentication
• Version: @farcaster/miniapp-sdk 0.1.7
• Authentication: JWT tokens via quickAuth

Documentation

• CLAUDE.md - Detailed architecture and development guidance
• tests/README.md - Comprehensive testing documentation

License

[Add license information]