Skip to content

CLAUDE.md

Latest commit

 

History

History
355 lines (286 loc) · 10.2 KB

CLAUDE.md

File metadata and controls

355 lines (286 loc) · 10.2 KB

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 containing multiple projects organized by company/product. All projects are included as Git submodules for centralized management and cross-project development.

Project Organization

central/
├── DNC/              # DoNotCarry delivery service projects
│   ├── apps/         # Mobile applications (React Native)
│   ├── backend/      # Laravel backends (v1 and v2)
│   └── utils/        # Shared utilities and packages
├── KCC/              # KCC Booklet projects
│   └── Booklet/      # Mobile app and Laravel backend
├── Metrix/           # Metrix Group projects
│   ├── AR-Character/ # Augmented reality project
│   └── mcp-insights/ # MCP server for Neo4j knowledge graphs
└── ReyemTech/        # Reyem Tech infrastructure and websites
    ├── cluster/      # Kubernetes cluster provisioning
    ├── gta-events/   # Laravel events application
    ├── sail/         # Docker/Helm scaffolding for Laravel
    └── website/      # Company website (Laravel)

Working with Submodules

Initial Setup

# Clone with all submodules
git clone --recursive git@github.com:user/central.git

# Or initialize submodules after cloning
git submodule update --init --recursive

Updating Submodules

# Update all submodules to latest commit on their tracked branch
git submodule update --remote

# Update a specific submodule
git submodule update --remote DNC/backend/v2

Working in Submodules

Each submodule is a full Git repository. To make changes:

cd DNC/backend/v2
# Make your changes
git add .
git commit -m "Description"
git push

# Return to parent repo and commit the submodule reference update
cd ../..
git add DNC/backend/v2
git commit -m "Update backend v2 submodule"
git push

Project-Specific Commands

DoNotCarry Backend v1 (Laravel 9 + Homestead/Vagrant)

Location: DNC/backend/v1/

Setup:

cd DNC/backend/v1
make environment  # Installs dependencies and sets up Homestead
vagrant up

Common Commands:

vagrant up          # Start VM
vagrant suspend     # Stop VM
vagrant ssh         # SSH into VM

Access:

DoNotCarry Backend v2 (Laravel 11 + Laravel Sail)

Location: DNC/backend/v2/

Setup:

cd DNC/backend/v2
cp .env.example .env
composer install
php artisan key:generate
php artisan jwt:secret
./vendor/bin/sail up -d

Common Commands:

# Lifecycle
./vendor/bin/sail up -d        # Start containers
./vendor/bin/sail down         # Stop containers
./vendor/bin/sail logs -f      # Follow logs
make start                     # Start with full setup (certs, hosts, etc.)
make stop                      # Stop containers
make restart                   # Restart Laravel container
make status                    # Check container status

# Development
./vendor/bin/sail artisan <command>       # Run Artisan commands
./vendor/bin/sail composer <command>      # Composer commands
./vendor/bin/sail npm <command>           # NPM commands
./vendor/bin/sail php <script>            # Run PHP scripts

# Testing & Code Quality
./vendor/bin/sail artisan test --env=testing
./vendor/bin/sail artisan test --env=testing tests/Feature/Cart/CartTest.php --filter=cart_total_is_correct
./vendor/bin/sail php ./vendor/bin/phpstan analyse
./vendor/bin/sail artisan pint

# Cache
./vendor/bin/sail artisan icons:cache

Access:

Important Notes:

  • v2 uses Filament v3 for admin panel
  • Uses Livewire Volt (functional and class-based components)
  • Uses Flux UI Pro for UI components
  • Has comprehensive Laravel Boost guidelines in CLAUDE.md file

DNC Mobile Apps (React Native)

Locations:

  • Customer App: DNC/apps/customer/
  • Driver App: DNC/apps/driver/
  • Fastlane Config: DNC/apps/fastlane/

These are React Native applications for iOS and Android.

DNC Utilities

Locations:

  • DNC/utils/api-sdk/ - API SDK
  • DNC/utils/filament-google-maps/ - Filament Google Maps integration
  • DNC/utils/geokit/ - Geolocation utilities

ReyemTech Cluster (Kubernetes Infrastructure)

Location: ReyemTech/cluster/

Setup:

cd ReyemTech/cluster
brew install tfenv
tfenv install 1.11.3
tfenv use 1.11.3
vim terraform.tfvars  # Configure your variables
terraform init
terraform plan
terraform apply

Components:

  • Traefik: Ingress routing with Let's Encrypt SSL
  • External DNS: Automated DNS management (AWS Route53)
  • OAuth2 Proxy: Google Authentication for Traefik dashboard
  • Redis Operator: Redis cluster management
  • MySQL Operator: High-availability MySQL with automated backups
  • Vault: Secret management with UI
  • External Secrets Operator (ESO): Syncs Vault with Kubernetes secrets

Post-Provisioning:

  1. Access Vault UI at https://vault.example.com
  2. Initialize and unseal Vault
  3. Run bootstrap script: kubectl exec -it vault-0 -n vault -- /vault/bootstrap/vault-bootstrap.sh

ReyemTech GTA Events (Laravel 12 + Inertia)

Location: ReyemTech/gta-events/

Setup:

cd ReyemTech/gta-events
composer install
cp .env.example .env
php artisan key:generate
php artisan jwt:secret
npm install

Common Commands:

php artisan serve
npm run dev
php artisan test --compact
vendor/bin/pint --dirty

Important Notes:

  • Laravel 12 with Inertia v2 + React 19
  • Uses Pest 4 for testing (including browser tests)
  • Uses Laravel Wayfinder for type-safe routing
  • Uses Laravel Fortify for authentication
  • Uses Tailwind CSS v4
  • Has comprehensive Laravel Boost guidelines in CLAUDE.md file

ReyemTech Sail Package

Location: ReyemTech/sail/

Custom Laravel package that provides Docker/Helm scaffolding for Laravel applications.

Key Command:

php artisan sail:build [options]

Non-interactive Flags:

  • --environments=local,production
  • --architectures=linux/amd64,linux/arm64
  • --repository=ghcr.io|registry.gitlab.com|docker.io|none
  • --organization=acme
  • --domains=app.example.com,api.example.com
  • --build-version=1.2.3
  • --push (push built images)
  • --use-previous (reuse last saved config)
  • --bump=patch|minor|major|no

Metrix MCP Insights

Location: Metrix/mcp-insights/

MCP server for MetrixGroup AI Insights Neo4j knowledge graph.

Setup:

cd Metrix/mcp-insights
pip install -e .
# or
uv pip install -e .

cp .env.example .env
# Configure Neo4j connection details

Running:

# Stdio (for Claude Code/Desktop)
python -m mcp_neo4j_insights.server
# or
mcp-neo4j-insights

# HTTP transport
mcp-neo4j-insights --transport http --port 8000

# SSE transport
mcp-neo4j-insights --transport sse --port 8000

Claude Code Configuration: Add to ~/.claude/mcp_servers.json:

{
  "mcp-neo4j-insights": {
    "command": "python",
    "args": ["-m", "mcp_neo4j_insights.server"],
    "env": {
      "NEO4J_URI": "bolt://localhost:7687",
      "NEO4J_USER": "neo4j",
      "NEO4J_PASSWORD": "your-password"
    }
  }
}

Available Tools:

  • Create: projects, behaviors, stakeholders, audiences, interviews, gaps, evidence, recommendations
  • Query: behaviors, gaps, interviews, project context, evidence chains
  • Bulk: create multiple gaps or evidence items
  • Export: PDF reports, Excel spreadsheets

Architecture Patterns

Laravel Projects

All Laravel projects in this monorepo follow similar patterns:

Environment Configuration:

  • Never use env() directly in code - only in config files
  • Use config('key') to access configuration values
  • All API keys and secrets go in .env files

Database Patterns:

  • Use Eloquent ORM with proper relationships and type hints
  • Avoid raw DB queries - prefer Model::query()
  • Use eager loading to prevent N+1 queries
  • Migrations must include all previous column attributes when modifying

Testing:

  • All code changes must have tests
  • Run minimal tests with filters: php artisan test --filter=testName
  • Use factories for test data
  • Follow existing test patterns (Pest or PHPUnit depending on project)

Code Style:

  • Run Laravel Pint before committing: vendor/bin/pint --dirty
  • Use curly braces for all control structures
  • Use constructor property promotion in PHP 8+
  • Always use explicit return type declarations

Submodule-Specific Guidelines

Each Laravel submodule may have its own CLAUDE.md file with detailed Laravel Boost guidelines. Always check for and follow project-specific guidelines:

  • DNC/backend/v2/CLAUDE.md - Laravel 11, Filament v3, Livewire Volt, Flux UI Pro
  • ReyemTech/gta-events/CLAUDE.md - Laravel 12, Inertia v2, React 19, Wayfinder, Pest 4

Key Considerations

When Working Across Projects

  1. Each submodule is an independent Git repository
  2. Changes in a submodule require commits in both the submodule AND parent repo
  3. Always check which directory you're in before running commands
  4. Submodules may use different PHP/Node versions - check project requirements

Development Environment

  • DNC Backend v1: Uses Vagrant/Homestead (VirtualBox or Parallels)
  • DNC Backend v2: Uses Laravel Sail (Docker)
  • Other Laravel Projects: May use different setups - check README
  • Kubernetes: ReyemTech cluster requires Terraform and cloud provider access

Testing Philosophy

  • Write tests for all new features and bug fixes
  • Run affected tests before finalizing changes
  • Use filters to run specific tests quickly
  • Browser tests available in Pest 4 projects

Security Considerations

  • Never commit .env files or secrets
  • All Laravel projects use JWT for API authentication
  • Backend v2 integrations: ShipEngine, Firebase, Bugsnag
  • Kubernetes cluster uses Vault for secret management