Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
317 lines (233 loc) · 8.25 KB

CONTRIBUTING.md

File metadata and controls

317 lines (233 loc) · 8.25 KB

Contributing to AetherGuard AI

Thanks for your interest in contributing! AetherGuard is a multi-service project spanning Rust, Python, and TypeScript — there's something for everyone.

Table of Contents

Code of Conduct

This project follows the Code of Conduct. By participating, you agree to uphold a welcoming and respectful environment for everyone.

Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/YOUR_USERNAME/aetherguard-ai.git
cd aetherguard-ai
  3. Add the upstream remote: 
    git remote add upstream https://github.com/maamir/AetherGuardAI.git
  4. Create a branch for your work: 
    git checkout -b feat/your-feature-name

Project Structure

aetherguard/
├── proxy-engine/       # Rust — high-performance request proxy (port 8080)
├── ml-services/        # Python — ML threat detection service (port 8001)
├── backend-api/        # Python — auth, tenants, policies, analytics (port 8081)
├── web-portal/         # React/TypeScript — end-user portal (port 3000)
├── admin-portal/       # React/TypeScript — admin dashboard (port 3001)
├── nodejs-sdk/         # TypeScript — official Node.js SDK
├── aws-infrastructure/ # AWS CDK — cloud infrastructure stacks
├── lambda/             # Python — AWS Lambda control plane functions
└── docs/               # Documentation

Each service is independently buildable and testable. You don't need to run the full stack to contribute to a single service.

How to Contribute

Reporting Bugs

Before opening an issue, please:

  • Search existing issues to avoid duplicates
  • Include the service name in the title (e.g., [ml-services] Hallucination detector returns false positives)
  • Provide steps to reproduce, expected vs actual behavior, and your environment

Suggesting Features

Open a GitHub Discussion first for larger ideas. For small improvements, a GitHub issue is fine.

Fixing Bugs / Implementing Features

  1. Comment on the issue to let others know you're working on it
  2. Follow the Development Setup below
  3. Write tests for your changes
  4. Submit a pull request referencing the issue

Development Setup

Prerequisites

  • Docker 20.10+ and Docker Compose 2.0+
  • Rust 1.70+ (for proxy-engine)
  • Python 3.9+ (for ml-services and backend-api)
  • Node.js 18+ (for web-portal, admin-portal, nodejs-sdk)
  • 8GB+ RAM (16GB recommended for running ML models)

Running the Full Stack

cp .env.example .env
docker compose up --build

Services will be available at:

Running Individual Services

Proxy Engine (Rust):

cd proxy-engine
cargo build
cargo run

ML Services (Python):

cd ml-services
pip install -r requirements.txt
uvicorn main:app --reload --port 8001

Backend API (Python):

cd backend-api
pip install -r requirements.txt
uvicorn main:app --reload --port 8081

Node.js SDK:

cd nodejs-sdk
npm install
npm run build

Admin Portal:

cd admin-portal
npm install
npm run dev

Coding Standards

Rust (proxy-engine)

  • Follow standard Rust idioms — run cargo fmt before committing
  • Use cargo clippy and resolve all warnings
  • Prefer async/await with Tokio for I/O operations
  • Document public APIs with /// doc comments

Python (ml-services, backend-api, lambda)

  • Follow PEP 8
  • Use type hints throughout
  • Format with black and lint with ruff: 
    black .
ruff check .
  • Use Pydantic models for request/response validation
  • Keep detector modules self-contained under detectors/

TypeScript (web-portal, admin-portal, nodejs-sdk, aws-infrastructure)

  • Strict TypeScript — no any unless absolutely necessary
  • Format with Prettier and lint with ESLint: 
    npm run lint
npm run format
  • Use functional React components with hooks
  • Keep AWS CDK constructs focused and composable

General

  • Keep commits atomic and descriptive (feat:, fix:, docs:, test:, refactor:)
  • No secrets, credentials, or PII in code or tests — use placeholders
  • Update relevant documentation when changing behavior

Testing

Rust

cd proxy-engine
cargo test

Python (ML Services)

cd ml-services
pytest tests/

Python (Backend API)

cd backend-api
pytest tests/

Node.js SDK

cd nodejs-sdk
npm test

Integration Tests

# Requires full stack running via Docker Compose
./tests/test-backend-api.sh
python tests/test_advanced_features.py

All PRs must pass existing tests. New features should include tests covering the happy path and key edge cases.

Submitting Changes

  1. Sync with upstream before opening a PR:

    git fetch upstream
git rebase upstream/main

  2. Push your branch:

    git push origin feat/your-feature-name

  3. Open a Pull Request against main with:

    • A clear title and description
    • Reference to the related issue (Closes #123)
    • Screenshots or curl examples for UI/API changes
    • Confirmation that tests pass

  4. PR review: A maintainer will review within a few days. Be responsive to feedback — PRs inactive for 30 days may be closed.

PR Title Format

Use Conventional Commits style:

feat(ml-services): add custom threshold support for toxicity detector
fix(proxy-engine): handle empty response body in egress stage
docs(nodejs-sdk): add streaming example to README
test(backend-api): add coverage for API key rotation endpoint

Issue Guidelines

Use the appropriate label when filing issues:

Label Use for
bug Something is broken
enhancement New feature or improvement
documentation Docs are missing or incorrect
good first issue Suitable for first-time contributors
help wanted Maintainers want community input
ml-services ML detection service
proxy-engine Rust proxy
backend-api Backend API service
sdk Node.js SDK
infrastructure AWS CDK / deployment

Areas We Need Help

If you're looking for where to start, these are active areas:

  • Python SDK — a Python equivalent of the Node.js SDK is on the roadmap
  • Go SDK — same, for Go developers
  • Kubernetes support — Helm chart and K8s manifests
  • Detector improvements — better accuracy, lower latency, new threat categories
  • Documentation — tutorials, integration guides, API reference improvements
  • Test coverage — more unit and integration tests across all services
  • Performance benchmarks — expanding the benchmark suite
  • Edge deployment — lightweight proxy for edge/on-prem environments

Check issues tagged good first issue for beginner-friendly tasks.

Security Vulnerabilities

Do not open public issues for security vulnerabilities.

Report them privately to: security@aetherguard.ai

We aim to respond within 48 hours and will coordinate a fix and disclosure timeline with you.

Questions?

Thanks for contributing to AetherGuard AI.