namaste/CLAUDE.md

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

cd lib && php composer.phar update -vv --prefer-dist

Running Brokers

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/:

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:

php lib/vendor/bin/phpunit            # Run unit test suite
php stubs/testMongo.php               # Manual stub tests
php stubs/testUsers.php

Schema Setup

php utilities/mysqlConfig.php         # Initialize MySQL/MariaDB schema
php utilities/mongoConfig.php         # Initialize MongoDB schema

Docker

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