Developer Guide

Developer Guide

Guide for contributing to Aletheia development.

---

Prerequisites

• Python 3.12+
• Node.js 18+
• Poetry (Python package manager)
• Git
• AWS CLI (for backend development)

---

Repository Structure

Aletheia/
├── extensions/chrome/     # Chrome Manifest V3 extension
├── extensions/firefox/    # Firefox Manifest V2 extension
├── src/                   # Python backend source
│   ├── guardrails/        # Safety and content filtering
│   └── signal_inspector/  # Signal analysis logic
├── tests/                 # Test suite
├── tools/                 # Development utilities
├── docs/                  # Documentation and ADRs
└── .github/               # CI/CD workflows

---

Local Setup

Clone the Repository

git clone https://github.com/martymcenroe/Aletheia.git
cd Aletheia

Install Python Dependencies

poetry install

Install Node Dependencies

npm install

Verify Setup

poetry run pytest
npm run lint

---

Development Workflow

Branch Strategy

• main - Production-ready code
• Feature branches: {issue-id}-short-description

Making Changes

1. Create a feature branch from main
2. Make your changes
3. Run tests: poetry run pytest
4. Run linting: npm run lint and poetry run ruff check
5. Commit with conventional format: type: description (ref #ID)
6. Push and create a Pull Request

Commit Message Format

type: description (ref #ID)

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation
• test: Tests
• chore: Maintenance

---

Testing

Run All Tests

poetry run pytest

Run with Coverage

poetry run pytest --cov=src --cov-report=term-missing

Run Specific Tests

poetry run pytest tests/test_semantic.py -v

Linting

# Python
poetry run ruff check .
poetry run mypy src/

# JavaScript
npm run lint

---

Extension Development

Load Extension in Chrome

1. Go to chrome://extensions/
2. Enable Developer mode
3. Click "Load unpacked"
4. Select extensions/chrome/

Load Extension in Firefox

1. Go to about:debugging
2. Click "This Firefox"
3. Click "Load Temporary Add-on"
4. Select extensions/firefox/manifest.json

Testing Changes

• Reload the extension after code changes
• Use browser DevTools to debug
• Check the Service Worker console for errors

---

Backend Development

AWS Configuration

Ensure AWS CLI is configured with appropriate credentials:

aws configure

Local Testing

The backend can be tested locally using:

poetry run python -m pytest tests/test_lambda_handler.py

Deployment

Backend deployment uses AWS SAM:

sam build
sam deploy --guided

---

Code Quality Standards

Python

• Style: Ruff for linting and formatting
• Types: Mypy for type checking
• Coverage: Minimum 70% test coverage

JavaScript

• Style: ESLint with project configuration
• No TypeScript (vanilla JS for extension simplicity)

Documentation

• Update relevant docs when making changes
• ADRs for significant architectural decisions
• Keep README current

---

Pre-commit Hooks

Install pre-commit hooks:

poetry run pre-commit install

Hooks include:

• Ruff (Python linting)
• ESLint (JavaScript linting)
• Gitleaks (secret scanning)

---

Getting Help

• Check existing issues
• Read the Architecture documentation
• Review ADRs in /docs

---

Last updated: 2026-01-06 10:28 CT