# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Repository Overview

This is a monorepo for Maple Open Technologies open-source software, organized into three major sections:
- **cloud/** - Backend web services (Go)
- **native/** - Native platform applications (Go CLI, WordPress plugins)
  - `native/desktop/` - Desktop applications (Go)
  - `native/wordpress/` - WordPress plugins (PHP)
- **web/** - Frontend applications (React + Vite)

The repository uses Go workspaces to manage multiple Go modules together.

## Architecture

### Backend Architecture (cloud/maplefile-backend)

The backend follows **Clean Architecture** with clear separation of concerns:

**Module Structure:**
- `internal/iam/` - Identity and Access Management module
- `internal/maplefile/` - MapleFile encrypted file storage module
- `internal/manifold/` - HTTP server infrastructure and middleware

**Layer Organization (within each module):**
- `domain/` - Domain entities and repository interfaces (business logic core)
- `repo/` - Repository implementations (data access)
- `usecase/` - Use cases/application services (business operations)
- `service/` - Service layer (orchestration)
- `interface/http/` - HTTP handlers and routes (delivery layer)
- `mocks/` - Generated mock implementations for testing

**Shared Packages (pkg/):**
- `storage/` - Database (Cassandra), cache (Redis), object storage (S3), memory
- `security/` - JWT, password hashing, encryption
- `emailer/` - Email sending (Mailgun)
- `distributedmutex/` - Distributed locking with Redis
- `httperror/` - HTTP error handling utilities
- `observability/` - Logging, metrics, tracing
- `logger/` - Structured logging with Uber Zap

**Dependency Injection:**
- Uses **Uber FX** for dependency injection
- Module initialization in `module.go` files
- Each module provides dependencies to the DI container

**Data Storage:**
- Primary database: **Cassandra** (distributed NoSQL database)
- Cache: **Redis**
- Object storage: **AWS S3-compatible** (Digital Ocean Spaces)
- GeoIP blocking: GeoLite2 database

### Frontend Architecture (web/maplefile-frontend)

- **React 19** with **Vite** build system
- **TailwindCSS** for styling
- **Dependency Injection** using InversifyJS
- **End-to-End Encryption (E2EE)** using libsodium-wrappers-sumo
- Client-side cryptography for secure file storage

### CLI Architecture (native/desktop/maplefile)

- Go-based CLI using **Cobra** command framework
- Implements complete E2EE key chain for MapleFile
- Features: user auth, collection management, file operations, sync
- Hybrid storage: local-only, cloud-only, or synchronized files

### WordPress Plugin Architecture (native/wordpress/maplepress-plugin)

- **PHP-based WordPress plugin** for MaplePress
- Follows WordPress plugin development best practices
- **API Integration**: Communicates with MaplePress backend via REST API
- **Authentication**: Uses API key authentication (Bearer token)
- **Features**: Cloud services platform for WordPress - offloads computationally intensive tasks
  - **Current**: Cloud-powered search with offsite processing, automatic content indexing
  - **Future**: File uploads, metrics, analytics, and more cloud services
- **Structure**:
  - `includes/` - Core plugin classes (OOP architecture)
  - `assets/` - CSS and JavaScript files
  - `languages/` - Translation files (i18n/l10n)
  - `tests/` - PHPUnit tests
- **Development**: Auto-mounted to local WordPress via Docker volume
- **Publishing**: Distributable to WordPress.org plugin directory

## Common Development Commands

### Root Level (Taskfile.yml)

```bash
# Update Go workspace
task updateworkspace

# Backend development
task backend-dev              # Start backend in dev mode
task backend-console          # Open console in running backend container
```

### Backend (cloud/maplefile-backend)

```bash
cd cloud/maplefile-backend

# Development
task dev                      # Start backend with docker-compose
task end                      # Stop backend
task console                  # Open bash in backend container
task cqlsh                    # Open Cassandra client (if Cassandra is used)

# Code Quality
task format                   # Format code with goimports
task lint                     # Run golint
task vet                      # Run go vet
task check                    # Run format + lint + vet

# Dependencies
task vendor                   # Download and vendor dependencies
task upgradelib               # Update all Go libraries

# Mock Generation
task mockgen                  # Generate all mock files for testing

# Build & Deploy (DevOps)
task deploy                   # Build and push production container
task deployqa                 # Build and push QA container
```

**Environment Configuration:**
- Copy `.env.sample` to `.env` and configure all variables
- Required: Cassandra hosts, Redis URI, AWS credentials, Mailgun settings

**Running Tests:**
```bash
go test ./...                 # Run all tests
go test ./internal/iam/...    # Test specific module
go test -v -run TestName      # Run specific test with verbose output
```

### Frontend (web/maplefile-frontend)

```bash
cd web/maplefile-frontend

# Development
task dev                      # Start Vite dev server (or: npm run dev)
npm run dev                   # Start development server directly

# Build
task build                    # Production build (or: npm run build)
npm run build                 # Build directly

# Code Quality
task lint                     # Run ESLint
npm run lint                  # Lint directly

# Deployment (requires SSH to worker-9)
task deploy                   # Shows deployment instructions
WORKER9_IP=<ip> task deploy-remote  # Deploy remotely via SSH

# See: cloud/infrastructure/production/setup/11_maplefile_frontend.md
# Version tracking: https://maplefile.com/version.json
```

### CLI (native/desktop/maplefile)

```bash
cd native/desktop/maplefile

# Build
go build -o maplefile .   # Build the CLI

# Development
go run main.go [command]      # Run directly without building
```

### WordPress Plugin (native/wordpress/maplepress-plugin)

```bash
cd native/wordpress/maplepress-plugin

# Development
task sync                     # Sync plugin to local WordPress container
task watch                    # Watch for changes and auto-sync
task logs                     # View WordPress debug logs
task shell                    # Open shell in WordPress container

# Code Quality
task lint                     # Run PHP CodeSniffer
task lint:fix                 # Auto-fix coding standards issues
task test                     # Run PHPUnit tests

# Build & Publish
task build                    # Build plugin zip for distribution
task clean                    # Clean build artifacts

# Dependencies
task install                  # Install Composer dependencies
task update                   # Update Composer dependencies
```

**WordPress Development:**
1. Start infrastructure: `cd ../../cloud/infrastructure/development && task dev:start`
2. Visit http://localhost:8081 and complete WordPress setup
3. Plugin is auto-mounted and ready to activate
4. Configure at Settings → MaplePress

## Key Technical Details

### Security & Encryption

**MapleFile E2EE Key Chain:**
1. User Password → Key Encryption Key (KEK)
2. KEK → Master Key
3. Master Key → Collection Keys
4. Collection Keys → File Keys
5. File Keys → Encrypted File Content

**Storage Modes:**
- `encrypted_only` - Only encrypted version stored (most secure)
- `hybrid` - Both encrypted and decrypted versions (default)
- `decrypted_only` - Only decrypted version (not recommended)

### Testing Strategy

- Mock generation using `go.uber.org/mock/mockgen`
- Mocks stored in `mocks/` directory within each module
- Use `task mockgen` to regenerate all mocks after interface changes

### Docker & Deployment

- Development: `docker-compose.dev.yml`
- Production: `docker-compose.prod.yml`
- Backend runs on port 8000
- Uses Digital Ocean Container Registry (`registry.digitalocean.com/ssp`)

### Database Migrations

- Migration files should be in `cloud/maplefile-backend` (check for migration directories)
- Uses `golang-migrate/migrate` for schema management

## Important Conventions

### Code Organization

1. **Always follow Clean Architecture layers**: Domain → Use Case → Service → Interface
2. **Repository pattern**: All data access through repository interfaces in `domain/*/interface.go`
3. **Dependency direction**: Outer layers depend on inner layers, never the reverse
4. **Module independence**: Each module (IAM, MapleFile) should be self-contained

### Naming Conventions

- Repository interfaces: Named in domain entities (e.g., `domain/federateduser/interface.go`)
- Implementations: In `repo/` directory
- Use cases: Verb-based names (e.g., `create.go`, `getbyid.go`, `update.go`)
- HTTP handlers: In `interface/http/` directory

### Error Handling

- Use `pkg/httperror` for consistent HTTP error responses
- Domain errors should be defined in domain layer
- Propagate errors up the stack with context

### Configuration

- All environment variables prefixed by component (e.g., `BACKEND_APP_`, `BACKEND_DB_`, `BACKEND_MAPLEFILE_`)
- Sensitive values marked as `XXX` in `.env.sample`
- Configuration loaded in `config/config.go`

## Module-Specific Notes

### IAM Module

**Domain Entities:**
- `federateduser` - User accounts with federated identity
- `auth` - Authentication sessions and tokens
- `recovery` - Account recovery mechanisms
- `keys` - Cryptographic key management

**Key Use Cases:**
- User registration, email verification, login (with OTP)
- Password recovery with cryptographic recovery keys
- Session management and token refresh

### MapleFile Module

**Domain Entities:**
- `user` - MapleFile user profiles
- `collection` - Encrypted file collections (folders)
- `file` - Individual encrypted files
- `dashboard` - User dashboard metrics
- `storagedailyusage` - Daily storage usage tracking
- `storageusageevent` - Storage usage event logging

**Key Features:**
- Collection sharing with granular permissions (read_only, read_write, admin)
- File synchronization (cloud-only, local-only, hybrid)
- End-to-end encryption at rest and in transit
- Storage usage tracking and quotas

## Development Workflow

1. **Start backend**: `cd cloud/maplefile-backend && task dev`
2. **Start frontend**: `cd web/maplefile-frontend && npm run dev`
3. **Make changes** in appropriate layer (domain → usecase → service → interface)
4. **Run code quality checks**: `task check` (format, lint, vet)
5. **Regenerate mocks** if interfaces changed: `task mockgen`
6. **Test changes**: `go test ./...` or `npm run test`
7. **Commit** with descriptive messages following repository conventions

## Troubleshooting

### Backend won't start
- Check `.env` file exists and is properly configured
- Verify Docker containers are running: `docker ps`
- Check logs: `docker logs mapleopentech_backend`

### Database connection issues
- Cassandra: Verify `DATABASE_HOSTS` points to running Cassandra cluster
- Redis: Verify `CACHE_HOST` and `CACHE_PORT` are correct
- Check Docker networking: Containers must be on same network

### Frontend build fails
- Clear node_modules and reinstall: `rm -rf node_modules && npm install`
- Check Node.js version compatibility with package.json

### Mock generation fails
- Ensure all Go tools are installed: Check `go.mod` tool section
- Run `go mod download` and `go mod vendor`