# CLAUDE.md

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

## Project Overview

**Namaste** is a custom PHP 7.4+ event-driven backend framework for multi-service microservice architectures. It is NOT built on Laravel or Symfony — it uses its own custom abstractions. All data access flows through AMQP message brokers backed by RabbitMQ.

## Commands

### Dependencies
```bash
cd lib && php composer.phar update -vv --prefer-dist
```

### Running Brokers
```bash
php scripts/startBrokers.php          # Start all brokers defined in XML config
bash scripts/launchBrokers.sh         # Wrapper script for daemon-mode launch
bash scripts/stopBrokers.sh           # Stop all running brokers
```

### Code Quality
All tools are Composer-installed in `lib/vendor/bin/`:
```bash
php lib/vendor/bin/phpcs [file]       # Code style
php lib/vendor/bin/phpmd [dir] text cleancode
php lib/vendor/bin/phploc [dir]
php lib/vendor/bin/phpcpd [dir]
```

### Testing
PHPUnit 6.5 is available. Stubs in `stubs/` are used for manual/ad-hoc testing:
```bash
php lib/vendor/bin/phpunit            # Run unit test suite
php stubs/testMongo.php               # Manual stub tests
php stubs/testUsers.php
```

### Schema Setup
```bash
php utilities/mysqlConfig.php         # Initialize MySQL/MariaDB schema
php utilities/mongoConfig.php         # Initialize MongoDB schema
```

### Docker
```bash
docker build . --tag=givingassistant/namaste:master
```

## Architecture

### Configuration System
- `config/namaste.xml` — base production config (service definitions, DB connections, broker counts, security settings)
- `config/env.xml` — environment-specific overrides (local DB hosts, credentials, feature flags)
- `config/env.admin.xml` — admin service overrides
- `gasConfig` class loads and merges these XML files; environment layering is how dev/staging/prod differ

### Service Architecture (Four Services)
- **appServer** — main application server with `rBroker` (read), `wBroker` (write), `mBroker` (mail/message)
- **admin** — admin service with `adminBrokerIn`, `adminBrokerOut`, `adminLogsBroker`, `adminSyslogBroker`, `adminGraphBroker`
- **segundo** — warehouse/cool-storage with `whBroker` and `cBroker` (Consolidated Sanctions List)
- **tercero** — user management with `uBroker` and `sBroker` (sessions)

### Data Layer Pattern
```
gacFactory (factory)
└── Resolves template name → instantiates correct widget
    ├── gacMongoDB — MongoDB adapter (sharding + replication support)
    ├── gacPDO — MySQL/MariaDB adapter (master-slave replication)
    └── gacDdb — DynamoDB adapter
```
All data classes extend `gaaNamasteCore` (abstract base), which defines the CRUD interface: `_createRecord`, `_fetchRecords`, `_updateRecord`, `_deleteRecord`.

### Data Templates (`classes/templates/`)
Each `.class.inc` file is a domain-specific schema class (e.g., `gatDonors`, `gatUsers`, `gatSessions`, `gatAudit`, `gatConsolidatedSanctionsList`). They extend `gaaNamasteCore` and implement schema-specific logic. Adding new data domains means creating a new template here.

### Message Flow
1. AMQP message arrives at broker
2. Broker parses metadata (sessionID, clientIP, etc.) via `gacMeta`
3. Broker calls `gacFactory::grabWidget()` with template name
4. Factory returns the appropriate database widget
5. Widget executes the CRUD operation
6. Response published back to AMQP reply queue

### Key Support Classes
| Class | Purpose |
|---|---|
| `gasConfig` | XML config loader/merger |
| `gasResourceManager` | Connection pooling, resource lifecycle |
| `gacErrorLogger` | Centralized logging |
| `gacBrokerClient` | AMQP publish/consume |
| `gacBrokerHelper` | Queue utilities |
| `gacUsers` | User CRUD, authentication, password hashing (ARGON2I) |
| `gasCache` | Memcached wrapper |
| `gacMigrations` | MongoDB ↔ MySQL data migration |
| `gasStatic` | Shared utility methods |

### Autoloading
Uses a **custom autoloader** (`autoloader.php`) — not PSR-4/Composer autoloading. All class files use `.class.inc` extension.

### Common/Shared Definitions
- `common/constants.php` — application-wide constants
- `common/functions.php` — global utility functions
- `common/errorCatalog.php` — error codes and messages
- `common/dbCatalog.php` — database schema definitions
- `common/cacheMaps.php` — Memcached key mappings

## Database Infrastructure
- **MongoDB**: Default port 27017 (dev), sharding via mongos at 27019 (prod). Three+ databases (namaste, admin, segundo, users), each with separate auth credentials.
- **MySQL/MariaDB**: Default port 3306. Master-slave replication in production. Schema in `schema/pdo/`.
- **DynamoDB**: Optional. Configured in `namaste.xml` under the DDB section.
- **Memcached**: Required for session caching and performance.

## Web Utilities (Admin/Debug)
Available at `http://namaste/utilities/`:
- `gaAdmin.php` — main admin dashboard
- `cashpeak.php` — Memcache reader/viewer
- `dumper.php` — log and metrics viewer
- `migrateData.php` — interactive data migration GUI