Getting Started (Developers)

🚀 New Developer Onboarding Sequence

Welcome to TradePsykl! This structured onboarding path will get you from zero to productive contributor in a systematic way. Follow this sequence in order — each phase builds on the previous.

Phase 1: Foundation

Goal: Understand what we're building and why

1. Read Project Context → docs/architecture/01-context.md — System boundaries, external integrations, user personas
2. Understand Architecture → docs/architecture/02-container.md — High-level container architecture (C4 model)
3. Review Key Decisions → docs/architecture/04-decisions.md — Why we chose Python, OpenTelemetry, Cloudflare, etc.
4. Trading Concepts Overview → docs/trading/overview.md — Weekly trading strategy fundamentals

Checkpoint: You should be able to explain: "What problem does TradePsykl solve?" and "What are the major system components?"

Phase 2: Environment Setup

Goal: Get a working development environment

1. Request Access → You'll receive an invitation to Cloudflare Access to view documentation (uses your GitHub account)
2. Install Prerequisites → Prerequisites below — Docker Desktop, VS Code, WSL2 (Windows)
3. Clone & Open in DevContainer → See Dev Container usage below
4. Open Multi-Root Workspace → trade_psykl.code-workspace (critical for Python imports)
5. Start Default Stack → docker compose up -d — Launch web + observability services
6. Verify Services Running → docker compose ps — Check health status
7. Test Endpoints → API (localhost:8000), UI (localhost:5173), Prometheus (localhost:9090)

Checkpoint: All services green in docker compose ps, you can hit the API and see JSON response

Phase 3: Development Workflow

Goal: Understand how to make changes and follow best practices

1. Read Developer Environment Guide → docs/infra/devops/developer-environment.md — Full workflow details
2. Understand Docker Profiles → docs/infra/devops/docker-profiles.md — How to run different service combinations
3. Review Branching & PR Process → docs/contributing.md — Git workflow and code review standards
4. Study CI/CD Pipeline → docs/infra/devops/ci-cd.md — Automated testing and deployment
5. Practice: Create a branch, make a trivial change (e.g., update API hello message), run tests, open a draft PR

Checkpoint: You've created a branch, modified code, run tests locally, and understand the PR workflow

Phase 4: Observability Deep Dive

Goal: Learn how we monitor and debug the system

1. Read Observability Architecture → docs/infra/devops/observability.md — Metrics, logs, traces strategy
2. Understand Service Telemetry → .github/copilot/observability.md — Implementation patterns
3. Explore Grafana Cloud → VS Code Task: "Observability: Open Grafana Cloud" — View live dashboards
4. Check Prometheus Metrics → http://localhost:9090 — Query service metrics
5. Review Existing Dashboards → docs/infra/devops/dashboards/README.md — API and Engine monitoring

Checkpoint: You can find a trace in Grafana Cloud, query metrics in Prometheus, and understand what signals each service emits

Phase 5: Service Deep Dive

Goal: Understand each service's architecture and responsibilities

Pick services based on your assigned work area. Read both main docs and Copilot guidance:

• API Service → src/api/main.py + .github/copilot/api.md
• Engine Service → src/engine/main.py + .github/copilot/engine.md
• UI Service → src/ui/ + .github/copilot/ui.md
• Data Layer → src/data/ + .github/copilot/data.md
• Documentation → docs/ + .github/copilot/docs.md

Checkpoint: You understand your service's entry points, configuration, telemetry, and test structure

Phase 6: Trading Domain Knowledge

Goal: Learn the financial domain concepts we're automating

1. Stock Selection Criteria → docs/trading/stock-selection.md — How we pick stocks (liquidity, momentum, sectors)
2. Tools & Screeners → docs/trading/tools-and-screeners.md — Finviz, TradingView, sector analysis platforms
3. Data Sources → docs/trading/data-sources.md — APIs for price data, earnings, fundamentals
4. Strategy Template → docs/trading/template.md — Standard format for documenting trading strategies
5. Review Component Architecture → docs/architecture/03-component.md — How data flows through the system

Checkpoint: You can explain pivot-based weekly trading and identify which components handle data ingestion vs strategy execution

Phase 7: Implementation Roadmap

Goal: Understand current progress and what's coming next

1. Review Implementation Plan → docs/architecture/05-implementation.md — Epics and task breakdown
2. Check Current Progress → Same file, look for [x] completed vs [ ] pending items
3. Understand Deployment Strategy → docs/infra/devops/deployment.md — How we release to production
4. Team Sync → Schedule pairing session to discuss your first assignment

Checkpoint: You know what's been built, what's in progress, and where you'll contribute first

---

📚 Quick Reference After Onboarding

Need to...

• Run services? → How to run (containers)
• Debug an issue? → Useful developer commands + Observability docs
• Understand a config file? → Check Developer Environment Guide or Docker Profiles
• Add a new feature? → Follow Contributing Guide → Branch → Implement → Test → PR
• Add observability? → See Observability Patterns
• Find architectural context? → Start with C4 Architecture Docs — System design documentation

---

📖 Detailed Setup Guide

This guide helps you run TradePsykl locally with Docker and understand the basics of the repo layout and CI.

• For deeper DevOps details, see docs/devops/docker.md and docs/devops/ci-cd.md.
• For the development environment workflow, see docs/devops/developer-environment.md.
• Documentation style: we reference files/paths rather than embedding configuration snippets.

What you'll set up

• Containers orchestrated by docker-compose.yml for:
  • Services: API (FastAPI), Engine, UI (static placeholder), CMS (docs), Data (MongoDB)
  • Observability: Prometheus (metrics), Promtail (log shipping to Grafana Cloud)
• Per-service Dockerfiles under src/ (see the Services section in docs/devops/docker.md)
• Optional VS Code Dev Container (.devcontainer/devcontainer.json)

Prerequisites

• Docker Desktop (Windows/macOS) or Docker Engine (Linux)
• Git
• VS Code (optional, recommended) with Dev Containers extension for a consistent environment
• Important: When using VS Code, open the multi-root workspace file trade_psykl.code-workspace (not the folder directly) to enable per-service Python import resolution. See docs/devops/developer-environment.md for details.

Repo layout (high level)

• src/api/ — FastAPI service (see src/api/main.py, src/api/requirements.txt)
• src/engine/ — strategy/rule engine (placeholder running main.py)
• src/ui/ — UI placeholder (served via serve on 5173)
• docs/ — VitePress documentation site (Dockerfile, package.json, and markdown sources)
• src/data/ — MongoDB container setup (pinned image; optional init scripts in initdb.d/)
• docs/devops/ — operations docs (docker.md, ci-cd.md)

How to run (containers)

This repo uses Compose profiles so you can run single-, multi-, or all-service stacks. The default profile is set in .env via COMPOSE_PROFILES=web,observability.

Default stack includes web services (API, UI, Data) + observability (Prometheus, Promtail). For comprehensive profile documentation, see docs/devops/docker-profiles.md.

Note: CMS (docs) runs only with explicit --profile cms or via native VitePress for development (see below).

• Start the default stack (uses .env):

docker compose up -d

• Start specific stacks by choosing profiles:

# Web services only (no observability)
docker compose --profile web up -d

# API + observability
docker compose --profile api --profile observability up -d

# Engine + Data + observability
docker compose --profile engine --profile data --profile observability up -d

# All services
docker compose --profile all up -d

• Check services:
  • API: http://localhost:8000/ → returns a JSON hello message
  • UI: http://localhost:5173/ → renders a simple hello page
  • Data: MongoDB listens on 27017 (no public web UI)
  • Prometheus: http://localhost:9090/ → metrics UI
  • Promtail: http://localhost:9080/ready → log shipping healthcheck

Note: For documentation development with live reload, use native VitePress (VS Code task: Docs: Dev Server (Native)) instead of the CMS container.

• Stop everything:

docker compose down

Tip: VS Code includes convenience tasks under .vscode/tasks.json (Run Task → "Compose: Up (default from .env)", etc.).

Ports and services

These are the default local ports exposed by the composition (refer to docker-compose.yml for authoritative mappings):

Service	Container	Host:Container	Purpose
API	api	8000:8000	FastAPI hello endpoint (GET /)
Engine	engine	8001:8080	Metrics endpoint (GET /metrics)
UI	ui	8080:8080	Static placeholder page
Docs	docs	5173:5173	Pre-built docs site (production)
Data	data	27017:27017	MongoDB (no web UI)
Prometheus	prometheus	9090:9090	Metrics UI and PromQL queries
Promtail	promtail	9080:9080	Log shipping healthcheck

Note: For documentation development, use native VitePress (VS Code task: Docs: Dev Server (Native)) instead of the CMS container for live reload.

Useful developer commands

• Start everything in the background (first run):

docker compose up --build -d

• Start in the background (later runs, no rebuild):

docker compose up -d

• See what’s running and health states:

docker compose ps

• Tail logs for all services (Ctrl+C to stop):

docker compose logs -f

• Tail logs for one service:

docker compose logs -f api

• Check observability endpoints:

# API metrics
Invoke-RestMethod http://localhost:8000/metrics

# Engine metrics
Invoke-RestMethod http://localhost:8001/metrics

# Prometheus UI
Start-Process http://localhost:9090

# Promtail health
Invoke-RestMethod http://localhost:9080/ready

• Rebuild a specific service without cache:

docker compose build --no-cache api

• Recreate just one service (no dependencies), rebuilding it:

docker compose up -d --no-deps --build api

• Prevent builds even if images are missing (will error if not built yet):

docker compose up -d --no-build

• Exec into a running container shell:

docker compose exec api sh

• Stop and remove containers, network (keep volumes):

docker compose down

• Stop and remove containers, network, and volumes (removes Mongo data):

docker compose down -v

• Optional cleanup of dangling images/build cache:

docker image prune -f
docker builder prune -f

Quick API test (PowerShell)

Use PowerShell to hit the API root and parse JSON:

Invoke-RestMethod http://localhost:8000/

Optional: Dev Container (VS Code)

• Open the repository in VS Code → "Reopen in Container". The devcontainer provides Python 3.12 + Node LTS plus Docker CLI access.
• After opening in devcontainer: Open the workspace file (File > Open Workspace from File… → trade_psykl.code-workspace) for proper per-service Python import resolution.
• Services run in their own containers (per-service Dockerfiles). The devcontainer installs only shared dev tools (linters/formatters); app dependencies are built inside each service image.
• Run Compose from the devcontainer terminal the same as on the host. For fastest file mounts on Windows, prefer WSL2 and keep the repo under WSL.
• See docs/devops/developer-environment.md for the end-to-end developer workflow and conventions.

CI/CD notes

• CI workflow lives at .github/workflows/ci.yml (see docs/devops/ci-cd.md).
• To conserve minutes, you can skip CI:
  • Include [skip ci] in the commit message (push) or in the PR title (pull_request). Jobs will not run.
  • You can always run manually from Actions via "Run workflow".

Mongo image pinning (brief)

• The Mongo container used by src/data/ is pinned to a specific 7.0.x patch version to reduce drift and improve reproducibility/security. Update the tag periodically as fixes are released, or pin to a digest for immutability.

Troubleshooting

• Port in use: change the host port mapping in docker-compose.yml or stop the conflicting app.
• Cache issues: use docker compose build --no-cache <service>.
• Windows/WSL2: ensure Docker Desktop uses the WSL2 backend for best performance.
• Import errors in VS Code: ensure you've opened trade_psykl.code-workspace (not the folder directly). See docs/devops/developer-environment.md.
• Profile confusion: see docs/devops/docker-profiles.md for comprehensive profile documentation and common scenarios.

What's next

• When the real backend is implemented, set the API entrypoint to a proper server command (e.g., uvicorn) and replace UI placeholder with Svelte/Vue dev server.
• See docs/devops/docker.md for more on services, healthchecks, and image pinning.
• See docs/devops/docker-profiles.md for comprehensive profile documentation and common development scenarios.
• See docs/devops/observability.md for observability architecture and Grafana Cloud integration.
• See docs/devops/developer-environment.md for the full development workflow including multi-root workspace setup.