Archive: Namaste PHP AMQP framework v1.0 (2017-2020)
952 days continuous production uptime, 40k+ tp/s single node. Original corpo Bitbucket history not included — clean archive commit.
This commit is contained in:
120
CLAUDE.md
Normal file
120
CLAUDE.md
Normal file
@@ -0,0 +1,120 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user