gramps
373ebc8c93
952 days continuous production uptime, 40k+ tp/s single node. Original corpo Bitbucket history not included — clean archive commit.
121 lines
5.0 KiB
Markdown
121 lines
5.0 KiB
Markdown
# 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
|