# PROJECT.md — Canonical Project Map

## 1. What is this project?
**Zyphon** is an enterprise-grade, high-throughput **Unified Messaging Gateway** built on Node.js, Fastify, and TypeScript. It normalizes outbound communication across Email (SendGrid, AWS SES, SMTP), SMS (Twilio), and WhatsApp (Meta Cloud API, Twilio) behind a single API endpoint (`POST /api/v1/messages/send`).

## 2. Why does it exist?
Modern microservice architectures frequently duplicate vendor-specific notification integrations, scatter external API credentials across disparate codebases, and struggle with automated provider failover. Existing messaging solutions often require heavyweight operational databases (PostgreSQL, MongoDB, Kafka) that impose unnecessary maintenance, backup, and on-call burdens. Zyphon provides a resilient, unified communication layer with **zero database dependencies**.

## 3. Who does it serve?
- **Platform & Infrastructure Architects**: Centralize all outbound communication credentials and routing policies in declarative GitOps manifests.
- **Site Reliability Engineers (SREs)**: Deploy a completely database-free, low-overhead container with append-only structured JSON logs (NDJSON) and live SSE observability.
- **Microservice & Product Developers**: Dispatch multi-channel communications using a single normalized request payload with consistent error codes and guaranteed failover.
- **Security & Compliance Officers**: Enforce fail-closed channel access control, zero plaintext credentials on disk, and automatic recipient PII masking.

## 4. What are the major capabilities?
1. **Unified Multi-Channel Ingress**: Normalized API endpoint for Email, SMS, and WhatsApp dispatches.
2. **Zero-Database Core**: Runtime state lives purely in declarative YAML manifests (`config/*.yaml`) and transient in-memory ring buffers.
3. **Automated Cascading Failover**: Configurable retry policies, circuit breakers, and automatic fallback provider cascades when upstream vendors fail or time out.
4. **Zero-Downtime Hot-Reload**: Inotify filesystem watcher applies configuration changes atomically without dropping in-flight requests.
5. **Real-Time Telemetry & Admin UI**: Next.js 14 dashboard streaming live NDJSON logs, provider health matrices, and topology via Server-Sent Events (SSE).
6. **Application Discovery Subsystem**: Container sidecar daemon registering microservice notification requirements.

## 5. What are the major boundaries?
- **Ingress Boundary**: Validates caller identity using pre-shared API key hashes (`X-Zyphon-App-Key`) and enforces per-application channel whitelists (`allowedChannels`).
- **Egress Boundary**: Dispatches outbound requests to external cloud APIs over TLS 1.3 with credential resolution via environment variables (`${ENV_VAR}`).
- **Control Plane Boundary**: The Admin Dashboard connects exclusively via read-only HTTP and SSE telemetry streams. No mutating API endpoints exist on the dashboard interface.

## 6. What are the important constraints?
- **Zero External Databases**: No SQL (Postgres/MySQL), NoSQL (Mongo), or Cache (Redis) instances may be introduced.
- **Fail-Closed Authorization**: Applications are denied dispatch on any channel not explicitly whitelisted in `config/applications.yaml`.
- **Zero Plaintext Secrets**: Config files must never store raw credentials; all secrets must resolve via `${ENV_VAR}` placeholders.
- **Normalized Provider Errors**: Upstream callers must never receive vendor stack traces or internal API credentials in error responses.

## 7. What are the important technologies?
- **Runtime**: Node.js 20+ LTS
- **Language**: TypeScript 5.x
- **API Framework**: Fastify 4.x
- **Dashboard Framework**: Next.js 14 (App Router) + React 18 + Tailwind CSS
- **Configuration**: YAML 1.2 (`yaml`) with JSON Schema / Zod validation
- **Logging**: Pino structured NDJSON streaming to `data/logs/`
- **Telemetry**: Server-Sent Events (SSE) and WebSockets

## 8. Where should an AI agent look for more information?
- **Operational Guidelines & Context Loading**: [`AGENTS.md`](AGENTS.md)
- **Machine-Readable Graph & Topology**: [`.project/manifest.json`](.project/manifest.json) and [`.project/graph/`](.project/graph/)
- **Product Requirements & Personas**: [`docs/PRD.md`](docs/PRD.md)
- **System Architecture & Data Flows**: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
- **Security & Safety Rules**: [`docs/RULES.md`](docs/RULES.md)
- **API Contracts & Config Schemas**: [`docs/DESIGN.md`](docs/DESIGN.md)
- **Implementation Backlog**: [`docs/TASKS.md`](docs/TASKS.md)
- **Architectural Decision Records**: [`docs/MEMORY.md`](docs/MEMORY.md)