mapleopentech/monorepo
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
monorepo/CLAUDE.md

11 KiB
Raw Blame History

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)

# 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)

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:

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)

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)

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)

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