managarten/.claude/GUIDELINES.md

Claude Code Guidelines

This directory contains comprehensive guidelines for working in the Mana Universe monorepo. These documents are designed to help Claude Code (and developers) maintain consistency across all projects.

Quick Reference

Document	Purpose
Code Style	Formatting, naming conventions, linting rules
Database	Drizzle ORM patterns, schema design, migrations
Testing	Jest/Vitest patterns, mock factories, coverage
Hono Server	Compute servers (Hono + Bun)
Error Handling	Go-style errors, error codes, Result types
SvelteKit Web	Svelte 5 runes, stores, routing
Expo Mobile	React Native, NativeWind, navigation
Authentication	Mana Core Auth integration
Design & UX	UI patterns, animations, accessibility

Core Principles

1. Explicit Over Implicit

• Use Go-style error handling with explicit Result<T> returns
• Prefer named exports over default exports
• Use explicit types instead of any

2. Consistency Over Preference

• Follow existing patterns in the codebase
• Use shared packages for common functionality
• Maintain consistent naming across all projects

3. Simplicity Over Cleverness

• Don't over-engineer solutions
• Avoid premature abstractions
• Keep files focused and small

4. Safety First

• Always validate user input
• Use parameterized queries (Drizzle handles this)
• Never expose sensitive data in responses

Technology Stack Summary

Layer	Technology	Notes
Package Manager	pnpm 9.15+	Workspace monorepo
Build System	Turborepo	Parallel task execution
Server	Hono + Bun	TypeScript, Drizzle ORM
Web	SvelteKit 2 + Svelte 5	Runes mode only
Mobile	Expo SDK 52-54	React Native, NativeWind
Database	PostgreSQL	Via Drizzle ORM
Auth	Mana Core Auth	Better Auth, EdDSA JWT
Storage	S3-compatible	MinIO

Project Structure

manacore-monorepo/
├── .claude/
│   ├── GUIDELINES.md          # This file
│   ├── guidelines/            # Detailed guidelines
│   └── templates/             # Code templates
├── apps/                      # Product applications
│   └── {project}/
│       ├── apps/
│       │   ├── server/        # Hono/Bun compute server
│       │   ├── web/           # SvelteKit web
│       │   ├── mobile/        # Expo app
│       │   └── landing/       # Astro landing
│       └── packages/          # Project-specific shared
├── packages/                  # Monorepo-wide shared
│   ├── shared-errors/         # Error codes & Result types
│   ├── shared-auth/           # Client auth service
│   ├── local-store/           # Local-first data layer (Dexie.js + sync)
│   └── ...
├── services/                  # Standalone microservices
│   └── mana-core-auth/        # Central auth service
└── CLAUDE.md                  # Root project overview

Before Making Changes

1. Read the relevant guideline for the area you're working in
2. Check existing patterns in similar files
3. Use shared packages when available
4. Follow the error handling pattern with Result types
5. Write tests for new functionality

Error Handling Philosophy

We use Go-style error handling across the entire stack:

// Backend services return Result<T>
const result = await userService.findById(id);
if (!result.ok) {
  // Handle error with error code
  throw new AppException(result.error);
}
return result.data;

// Frontend handles errors explicitly
const { data, error } = await api.getUser(id);
if (error) {
  showToast(error.message);
  return;
}

See Error Handling for complete details.

Quick Commands

# Development
pnpm install                    # Install dependencies
pnpm {project}:dev              # Start project (all apps)
pnpm dev:{project}:server       # Start just Hono server
pnpm dev:{project}:local        # Start sync + server + web (no auth)
pnpm dev:{project}:web          # Start just web

# Quality
pnpm type-check                 # TypeScript validation
pnpm format                     # Format code
pnpm test                       # Run tests

# Database (for apps with Drizzle in server)
pnpm --filter @{project}/server db:push    # Push schema changes
pnpm --filter @{project}/server db:studio  # Open Drizzle Studio