diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a09509c..f6dee39 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,69 +1,139 @@ # Contributing to SpectraGraph Thank you for your interest in contributing to **SpectraGraph** 🌌 -SpectraGraph is a production-grade OSINT intelligence platform designed for ethical investigations, transparent reporting, and repeatable graph analysis. +SpectraGraph is a **production-grade OSINT intelligence platform** designed for ethical investigations, transparent reporting, and repeatable graph-based analysis. -Because of its **multi-service architecture** and **ethical constraints**, contributions must follow clear guidelines. This document explains how to get started, where changes belong, and how to submit high-quality pull requests. +Because SpectraGraph operates across **multiple services**, handles **sensitive intelligence workflows**, and enforces **strict ethical boundaries**, contributions must follow clearly defined rules. -Please read this document fully before contributing. +This document explains: +- How to get started +- How the architecture is structured +- Where different kinds of changes belong +- How to submit high-quality, reviewable pull requests + +> ⚠️ Please read this document fully before contributing. +> Pull requests that do not follow these guidelines may be closed without review. --- -## 🧠 Project Philosophy +## 🧠 Project Philosophy (Non-Negotiable) -SpectraGraph is built around three core principles: +SpectraGraph is built around three core principles. +All contributions are evaluated against them. -1. **Architectural integrity** - Clear boundaries between frontend, API, orchestration, transforms, and shared types. +### 1. Architectural Integrity +- Clear, enforced boundaries between services +- Strict dependency direction +- No hidden coupling or shortcuts -2. **Ethical OSINT practices** - No intrusive scanning, no abuse-enabling features, no unsafe defaults. +### 2. Ethical OSINT Practices +- No intrusive scanning +- No abuse-enabling features +- No unsafe defaults +- No functionality designed to evade safeguards -3. **Production-grade reliability** - Typed data models, test coverage, and predictable workflows. +### 3. Production-Grade Reliability +- Typed data models +- Test coverage where applicable +- Predictable, repeatable workflows -Contributions that violate these principles will not be accepted. +❌ Contributions that violate these principles **will not be accepted**. --- -## 🧩 Repository Overview & Architecture Boundaries +## 🧩 Repository Architecture & Dependency Model + +SpectraGraph is a **monorepo** with a **strict, one-directional dependency flow**: + -SpectraGraph is a monorepo with **strict dependency direction**: -**Frontend β†’ API β†’ Core β†’ Transforms β†’ Types** +Dependencies may only flow **downward**. + +--- -### Monorepo Layout +## πŸ“ Repository Layout + +``` SpectraGraph/ β”œβ”€β”€ spectragraph-core/ # Orchestration, Celery, vault, graph logic -β”œβ”€β”€ spectragraph-types/ # Shared Pydantic entity models -β”œβ”€β”€ spectragraph-transforms/ # OSINT enrichment plugins -β”œβ”€β”€ spectragraph-api/ # FastAPI service -β”œβ”€β”€ spectragraph-app/ # Vite/React frontend +β”‚ β”œβ”€β”€ workflows/ # Investigation & execution workflows +β”‚ β”œβ”€β”€ graph/ # Graph construction & traversal logic +β”‚ β”œβ”€β”€ vault/ # Secrets & credential access layer +β”‚ β”œβ”€β”€ tasks/ # Celery task definitions +β”‚ └── tests/ +β”‚ +β”œβ”€β”€ spectragraph-types/ # Shared Pydantic schemas (single source of truth) +β”‚ β”œβ”€β”€ entities/ # Entity models (IP, Domain, Email, etc.) +β”‚ β”œβ”€β”€ relations/ # Graph edge definitions +β”‚ └── tests/ +β”‚ +β”œβ”€β”€ spectragraph-transforms/ # Stateless OSINT enrichment plugins +β”‚ β”œβ”€β”€ features/ # Individual enrichment features / transforms +β”‚ β”‚ β”œβ”€β”€ domain/ # Domain-related transforms +β”‚ β”‚ β”œβ”€β”€ ip/ # IP-related transforms +β”‚ β”‚ └── email/ # Email-related transforms +β”‚ β”œβ”€β”€ base.py # Transform base class +β”‚ └── tests/ +β”‚ +β”œβ”€β”€ spectragraph-api/ # FastAPI service layer +β”‚ β”œβ”€β”€ routes/ # API route definitions +β”‚ β”œβ”€β”€ schemas/ # Request/response validation +β”‚ β”œβ”€β”€ dependencies/ # Auth, context, lifecycle hooks +β”‚ └── tests/ +β”‚ +β”œβ”€β”€ spectragraph-app/ # Vite + React frontend +β”‚ β”œβ”€β”€ features/ # UI feature modules +β”‚ β”œβ”€β”€ components/ # Reusable UI components +β”‚ β”œβ”€β”€ pages/ # Route-level pages +β”‚ └── tests/ +β”‚ β”œβ”€β”€ docker-compose*.yml β”œβ”€β”€ Makefile β”œβ”€β”€ ETHICS.md β”œβ”€β”€ DISCLAIMER.md └── CONTRIBUTING.md +``` + +--- + +## 🧱 Architectural Rules (Strictly Enforced) + +### Frontend +- May communicate **only** with the API +- No direct access to databases, Core, or Transforms +- Must respect investigation workflows and safety constraints + +### API +- Handles request validation and response shaping +- May call Core and read storage +- ❌ Must not contain business or orchestration logic + +### Core +- Central orchestration layer +- Manages Celery tasks, secrets, and execution flow +- Acts as the system’s control plane -### Architectural Rules (Important) +### Transforms +- Must be **stateless and isolated** +- No shared state +- No orchestration logic +- No direct database access -- **Frontend** may only talk to the API -- **API** may call Core and read storage -- **Core** orchestrates Celery tasks and secrets -- **Transforms** must be stateless and isolated -- **Types** are the single source of truth for schemas +### Types +- Single source of truth for schemas +- Shared across all services +- Pydantic models only -❌ Do not introduce circular dependencies -❌ Do not bypass Core to call Transforms directly -❌ Do not duplicate entity schemas outside `spectragraph-types` +❌ No circular dependencies +❌ No bypassing Core to call Transforms directly +❌ No schema duplication outside `spectragraph-types` --- ## πŸš€ Getting Started (Development Setup) ### Prerequisites - -- Docker (required) +- Docker (**required**) - Python 3.10+ - Poetry - Node.js (for frontend) @@ -76,144 +146,173 @@ SpectraGraph/ git clone https://github.com//spectragraph.git cd spectragraph ``` - -### Environment Setup -```cp .env.example .env``` - - -Populate required environment variables before starting services. - -**Install Dependencies** -+ Python (workspace) -```poetry install``` - -+ Frontend +Environment Configuration +``` +cp .env.example .env +``` +Install Dependencies Python (workspace) +```bash +poetry install +``` +Frontend ```bash cd spectragraph-app npm install -``` - -+ Start the Development Stack -```make dev``` +``` +Start the Development Stack +```bash +make dev +``` -***This launches:*** +## ▢️ Start the Development Stack -* Postgres -* Redis -* Neo4j -* FastAPI -* Celery worker -* Fronend UI +```bash +# Start all services +make dev -***Access the UI at:*** -```http://localhost:3000``` +# Access the UI +# http://localhost:3000 +# Stop all services +make down -***Stop everything with:*** -```make down``` +##Services Started -### πŸ§ͺ Testing Requirements +PostgreSQL +Redis +Neo4j +FastAPI +Celery worker +Frontend UI -**Each module has its own test suite.** +``` +πŸ§ͺ Testing Requirements -***Core** ```bash +# Core tests cd spectragraph-core poetry run pytest -``` -***Transforms*** -```bash +# Transform tests cd spectragraph-transforms poetry run pytest -``` -***API*** -```bash +# API tests cd spectragraph-api poetry run pytest + ``` +Test Policy -**βœ… Tests must pass before opening a PR** -**❌ PRs without tests (where applicable) may be rejected** - -### 🧱 Where to Add Changes -**Adding a New Transform** -* Location: spectragraph-transforms/ - -* Must subclass Transform -* Must declare params_schema -* Must implement: - + preprocess() - + scan() - + Secrets must be retrieved via Vault - + No direct network abuse or scraping beyond ethical OSINT norms - -**Adding or Modifying Entity Schemas** -* Location: spectragraph-types/ -* Use Pydantic models only -* Changes here impact multiple services -* Breaking schema changes require discussion first - -**API Changes** -* Location: spectragraph-api/ -* Use FastAPI routing conventions -* Validate inputs strictly -* No business logic leakage into API routes - -**Frontend Changes** -* Location: spectragraph-app/ -* Must respect investigation workflows -* UI should not expose unsafe or misleading actions - -### 🌿 Branching & Commit Guidelines -***Branch Naming*** -```bash +βœ… All tests must pass before opening a PR + +❌ PRs without tests (where applicable) may be rejected + +--- + +## 🧱 Where to Add Changes + +### βž• Adding a New Transform +**Location:** `spectragraph-transforms/features/` + +**Requirements:** +- Must subclass `Transform` +- Must declare `params_schema` +- Must implement: + - `preprocess()` + - `scan()` +- Secrets must be retrieved via Vault +- No intrusive scanning or scraping beyond ethical OSINT norms + +--- + +### 🧬 Adding or Modifying Entity Schemas +**Location:** `spectragraph-types/` + +**Rules:** +- Pydantic models only +- Changes impact multiple services +- Breaking schema changes require prior discussion + +--- + +### 🌐 API Changes +**Location:** `spectragraph-api/` + +**Rules:** +- Follow FastAPI routing conventions +- Validate inputs strictly +- No business logic leakage into routes + +--- + +### 🎨 Frontend Changes +**Location:** `spectragraph-app/` + +**Rules:** +- Must respect investigation workflows +- Must not expose unsafe or misleading actions +- UX should reinforce ethical usage + +--- + +## 🌿 Branching & Commit Guidelines + +### Branch Naming +```text feature/ fix/ docs/ + ``` -Example: -`git checkout -b feature/domain-transform` +## πŸ” Pull Request Guidelines -***Commit Messages*** -Use clear, descriptive messages: -```bash -feat: add domain enrichment transform -fix: handle missing vault secrets gracefully -docs: clarify investigation workflow -``` +### When opening a Pull Request: +- Target the `main` branch +- Keep PRs focused (one concern per PR) +- Clearly explain **what changed** and **why** +- Link related issues or discussions +- Include screenshots for UI changes (if applicable) + +### PRs may be requested to: +- Add or improve tests +- Split changes into smaller PRs +- Adjust architectural placement to respect boundaries + +--- -### πŸ” Pull Request Guidelines +## πŸ” Ethics, Safety & Responsible Disclosure -When opening a PR: -* Target the main branch -* Keep PRs focused (one concern per PR) -* Explain what changed and why -* Link related issues if applicable -* Include screenshots for UI changes -* PRs may be requested to: -* Add tests -* Split changes -* Adjust architecture placement +SpectraGraph is an **OSINT intelligence platform**. +All contributors must follow strict ethical guidelines. -### πŸ” Ethics, Safety & Responsible Disclosure +### Required: +- Read and follow `ETHICS.md` -SpectraGraph is an OSINT platform. All contributors must follow ethical guidelines. +### Do **NOT** add features that: +- Enable intrusive scanning +- Circumvent safeguards +- Encourage misuse or harm + +### Security Disclosure: +- πŸ”’ Security vulnerabilities must be reported **privately** +- Do **not** disclose security issues via public issues or PRs + +If you are unsure about a feature’s ethical or safety impact, +**open a discussion before coding**. + +--- -**Read and follow ETHICS.md** -+ Do not add features that: -+ Enable intrusive scanning -+ Circumvent safeguards -+ Encourage misuse -+ Security issues should be reported privately, not via public issues -+ If unsure, open a discussion before coding. +## πŸ“Ž Final Notes -### πŸ“Ž Final Notes +SpectraGraph is intentionally strict about structure, safety, and ethics. -***SpectraGraph is intentionally strict about structure and ethics.*** -***This keeps the platform reliable, defensible, and scalable.*** +This discipline keeps the platform: +- Reliable +- Defensible +- Scalable +- Trusted -**Thank you for contributing responsibly 🌌** \ No newline at end of file +**Thank you for contributing responsibly to SpectraGraph** 🌌