Developer Guide

Developer Guide

Guide for contributing to Aletheia development.

---

Prerequisites

• Python 3.12+
• 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
│   ├── auth/                # Authentication subsystem
│   │   ├── anonymize.py     # User ID anonymization
│   │   ├── auth_middleware.py # @require_auth decorator
│   │   ├── coupon_handler.py # Coupon redemption
│   │   ├── jwt_service.py   # JWT creation/validation
│   │   ├── metrics_handler.py # Admin metrics
│   │   ├── stripe_handler.py # Stripe billing
│   │   ├── tier_config_service.py # Tier management
│   │   └── token_cap_service.py # Rate limiting
│   ├── guardrails/          # Content safety filtering
│   ├── signal_inspector/    # Signal analysis logic
│   ├── models/              # Data models (rate_limit, etc.)
│   ├── lambda_function.py   # Agent Lambda handler
│   └── lambda_auth_function.py # Auth Lambda handler
├── tests/                   # 975+ unit tests
│   ├── unit/                # Unit tests
│   └── integration/         # Integration tests
├── tools/                   # Admin CLIs
│   ├── admin_subscriptions.py
│   ├── admin_coupons.py
│   ├── admin_token_cap.py
│   ├── admin_id_resolve.py
│   └── merge_pr.py
├── docs/                    # Documentation
│   ├── adrs/                # Architecture Decision Records
│   ├── lld/                 # Low-Level Design documents
│   ├── audits/              # Audit reports
│   ├── runbooks/            # Operational runbooks
│   ├── reports/             # Implementation & test reports
│   └── retrospectives/      # Lessons learned
├── provision.sh             # AWS infrastructure provisioning
└── pyproject.toml           # Python project configuration

---

Local Setup

Clone the Repository

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

Install Dependencies

poetry install

Install Pre-commit Hooks

poetry run pre-commit install

Verify Setup

poetry run pytest tests/ --ignore=tests/integration -q
poetry run ruff check src/ tools/ tests/
poetry run mypy src/ tools/ --ignore-missing-imports

---

Development Workflow

Branch Strategy

• main — Production-ready code
• Feature branches: {issue-id}-short-description
• Worktrees: git worktree add ../Aletheia-{ID} -b {ID}-short-desc

Making Changes

1. Create a worktree from main
2. Write LLD in docs/lld/active/ (docs before code)
3. Implement with tests
4. Create implementation report and test report in docs/reports/{ID}/
5. Commit: type: description (close #ID)
6. Push and create Pull Request
7. Merge via poetry run python tools/merge_pr.py --pr NUMBER

Commit Message Format

type: description (close #ID)

Types: feat, fix, docs, test, chore

Pre-Merge Gate

Every PR requires before merge:

• docs/reports/{IssueID}/implementation-report.md
• docs/reports/{IssueID}/test-report.md

---

Testing

Run All Tests

poetry run pytest tests/ --ignore=tests/integration -q

Run Specific Tests

poetry run pytest tests/unit/test_jwt_service.py -v

Linting

poetry run ruff check src/ tools/ tests/
poetry run mypy src/ tools/ --ignore-missing-imports

Pre-commit Hooks

12 hooks run on every commit:

1. Trim trailing whitespace
2. Fix end of files
3. Check YAML/JSON syntax
4. Check for large files
5. Detect private keys
6. Ruff (Python lint)
7. Mypy (type checking)
8. Gitleaks (secret scanning)
9. ESLint security rules (JavaScript)
10. Project policy compliance
11. Pre-merge gate (reports required)
12. Audit record compliance

---

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

---

Backend Development

Infrastructure Provisioning

# Requires configured AWS CLI
./provision.sh

This creates/updates: DynamoDB tables, IAM roles, Lambda functions, Lambda layer, Function URLs, CloudWatch log groups.

Key Architecture Decisions

See ADRs (19 records covering permissions, auth, rate limiting, CloudFlare migration, and more).

---

Getting Help

• Check existing issues
• Read the Architecture documentation
• Review ADRs

---

Last updated: 2026-02-19