Development & Contribution

We welcome contributions from the community! To keep the codebase stable and maintainable, please follow these guidelines and testing workflows before submitting a pull request. DepthSight is licensed under AGPL-3.0 — all contributions must be compatible with this license.

---

Development Workflow

Recommended Contribution Path

1. Architecture Familiarity: Read the Architecture Overview to understand how the 10+ services communicate and the data flow patterns.
2. Environment Setup: Copy .env.example to .env and configure:
   • Database connection (PostgreSQL 15)
   • Redis connections (System + Market Data)
   • Exchange API keys (Binance testnet recommended)
   • JWT secret key
   • AI provider keys (optional)
3. Choose Your Scope: DepthSight is modular. Identify which component you need to change:
   • Backend: bot_module/ (trading engine), api/ (REST/WS), market_data_service.py
   • Frontend Web: frontend/ (React + shadcn/ui)
   • Mobile PWA: pwa/ (React + i18n)
   • Landing/Docs: lending/ (Next.js + Fumadocs)
4. Write Tests First: Add regression tests in tests/ for any new logic or bug fixes. See testing guidelines below.
5. Implement: Make your changes following the coding standards.
6. Verify: Run tests, linting, and builds for all affected modules.

---

Testing Guidelines

Before submitting any code changes, verify your changes across all relevant modules.

Backend Tests (Pytest)

The backend test suite spans ~150+ test files covering unit, integration, and e2e tests:

Sources: Backend Test Commands

Test Categories:

Directory	Focus	Count
tests/e2e/	End-to-end integration tests	5+
tests/test_*.py	Unit tests per module	140+
tests/conftest.py	Shared fixtures (mock DB, mock exchange)	-
tests/mocks.py	Mock classes for testing	-

E2E & Exchange Tests

[!NOTE] Several integration tests connect to actual exchange testnets (Binance, Bybit, etc.). If you do not provide active TESTNET_* API keys in your .env file, these tests will automatically be skipped. We recommend adding testnet keys to ensure order execution logic is fully verified.

Sources: E2E Test Commands

Frontend Web Checks

Ensure the React web dashboard compiles and linting passes:

Sources: Frontend Build Commands

The frontend uses:

• React 19 with TypeScript
• shadcn/ui for component library
• Tailwind CSS for styling
• Vite for bundling
• dnd-kit for drag-and-drop strategy editor

PWA Client Checks

Ensure the mobile PWA client compiles correctly:

Sources: PWA Build Commands

The PWA uses:

• React 19 with TypeScript
• Vite for bundling
• i18next for internationalization (en/ru)
• Google OAuth for authentication

Landing / Docs Site Checks

Sources: Landing Build Commands

The docs site uses:

• Next.js 16.1
• Fumadocs for MDX documentation rendering
• Three.js for 3D visualizations

---

Coding Standards

Python Backend

Requirement	Standard
Version	Python 3.11+
Style	PEP 8 (black formatter, 100 char lines)
Typing	Full type annotations (mypy strict)
Async	asyncio for I/O, multiprocessing for CPU
Error Handling	Always log exceptions with exc_info=True
Imports	Standard lib → Third-party → Local (sorted)

TypeScript Frontend

Requirement	Standard
Version	TypeScript 5.x
Style	ESLint + Prettier (2-space indent)
Components	Functional + hooks (no classes)
State	React hooks (useState, useReducer)
Styling	Tailwind CSS utility classes
Forms	React Hook Form + Zod validation

---

Configuration & Security Rules

Never Commit Secrets

Double check that your API keys, encryption secrets, database backups, or custom .env configurations are not staged for commit:

Sources: Git Security Check

Environment Variables

If your feature introduces a new environment variable, document it in .env.example with a placeholder description following the existing format:

Sources: .env.example Format

API Key Security

• Exchange API keys are encrypted at rest using Fernet symmetric encryption.
• API key hashes (SHA-256) are stored for deduplication — plaintext keys are never logged.
• Paper trading defaults: when developing order execution logic, default testing to PaperTradingExecutor or exchange Testnets.

Branch Strategy

Sources: Branch Strategy Reference

---

Pull Request Checklist

Before pushing modifications or submitting a PR:

• Backend tests: pytest completes with 100% passed
• Frontend build: cd frontend && npm run build succeeds
• PWA build: cd pwa && npm run build succeeds
• Clean state: git status shows no untracked cache files, database logs, or .update_trigger files
• No secrets: Double-check no .env, API keys, or certificates are staged
• Docs updated: If startup commands, dependencies, or APIs changed, update the corresponding docs
• Changelog: If applicable, add entry to CHANGELOG
• Migration: If new DB columns/tables added, include Alembic migration script

---

Quick Reference

Sources: Full Validation Commands