# Developer Architecture Guide

This guide is for developers and adaptors who want to modify, extend, or integration-test the RAVENSTRIKE application codebase.

## Codebase Component Mapping

The system logic is divided into modular ESM files. Here is the layout of the source files and their design intents:

- **CLI/Dashboard Entries**:
  - `bin/ravenstrike.js`: Configures the commander CLI parameters and command routing.
  - `src/cli/run.js`: Direct interface executing a single run and outputting raw JSON to `stdout`.
  - `src/cli/initWorkspace.js`: Prepares developer workspace configurations for Windsurf, Cursor, and Claude.
  - `src/dashboard/index.js`: Sets up the local `blessed` terminal interface.

- **Pipeline Coordination**:
  - `src/core/router.js`: Parses inputs to determine if a specific stage command (e.g. `/scope`, `/sigma`) was requested or routes to the full pipeline.
  - `src/core/orchestrator.js`: Manages the state machine. Sequential stage outputs are passed from step to step and validated against schemas.
  - `src/core/validation.js`: Registers and compiles the schemas located in `schemas/` using `Ajv2020` compiler. Enforces output shape.

- **Pipeline Implementations**:
  - `src/core/modules.js`: Implements the 7 pipeline phases. The current operational release contains deterministic reference values modeled around an encoded PowerShell threat scenario. Developers adding support for new threat vectors or logic will modify this file.
  - `src/core/platforms.js`: Validates platform tags. Supported: `QRadar`, `CrowdStrike`, `Sentinel`, `Elastic`, `Splunk`, `Generic`.
  - `src/core/selfLearning.js`: In-memory baseline tracker. Observes inputs and tracks command frequency. Handles self-healing mock fallback generation if validation or module execution fails.

---

## State Machine & Flow Diagram

The orchestrator enforces the following data pipeline sequence:

```text
Input ➔ Router ➔ Ingest ➔ Scope ➔ Enrich ➔ Detect ➔ Cover ➔ Triage ➔ Package
                  |        JSON Schema Validation (Ajv)        |
                  +---- In-Memory Baseline + Healing Guard ----+
```

### State Transitions
1. `RECEIVED` ➔ Input raw string ingested.
2. `ROUTED` ➔ Intent identified (confidence score calculated).
3. `MODULE_EXECUTED` ➔ Stage logic runs.
4. `VALIDATED` ➔ Output schema matched.
5. `RETURNED` ➔ Package returned.

If confidence is `< 0.70`, the system transitions to `DISAMBIGUATE` and asks for clarification. If validation fails, it triggers the `SelfHealingGuard` and returns a minimal safe telemetry envelope instead of crashing.

---

## Output Validation & Schemas

Schemas are defined in `schemas/` using JSON Schema Draft 2020-12. Before any module output is returned by the orchestrator, it is passed through `validateModuleOutput` in `src/core/validation.js`. 

To extend modules or add new detection scenarios:
1. Define the updated schema in the relevant `schemas/module_*.schema.json`.
2. Update the tests under `tests/validation.test.js`.
3. Modify the corresponding module implementation in `src/core/modules.js`.

---

## LLM Adapter Boundary

RAVENSTRIKE includes an adapter boundary under `src/adapters/llm/` to integrate with Large Language Models.

- **Base Class**: `LLMAdapter` (`src/adapters/llm/base.js`) defines the common contract.
- **Mock Adapter**: `MockAdapter` (`src/adapters/llm/providers.js`) returns static mocked messages. It requires no configurations.
- **OpenAI Adapter**: `OpenAIAdapter` (`src/adapters/llm/providers.js`) is an OpenAI-compatible HTTP fetch client.

Developers seeking to add support for alternative local or cloud APIs (e.g. Anthropic, Google Gemini, Ollama) should create a new class subclassing `LLMAdapter` and register it in `createAdapter` inside `src/adapters/llm/providers.js`.

---

## Trust Boundaries & Data Safety

- **Unsanitized Inputs**: Treat all analyst inputs as untrusted data.
- **Credentials**: Ensure `OPENAI_API_KEY` is read from environmental contexts and never committed.
- **Rule Deployments**: RAVENSTRIKE outputs detection rules (Sigma/Queries) for manual analyst vetting. Do not connect these outputs to auto-deployment tools without manual approval gates.