Skip to content

Contributing

Thanks for your interest in LogSys. This guide covers the workflow, conventions, and quality gates every contribution must pass.

Repository Layout

Path Contents
backend/ FastAPI API, models, routers, Alembic migrations
services/ Collectors, pipeline, vector config, simulators
admin/ React 19 frontend (Vite + TanStack)
docs/ This documentation (MkDocs)
docker-compose.yml Full-stack orchestration
tests/ Backend tests (pytest)

Workflow

  1. Create a branch from dev — never commit directly to dev
  2. Make focused changes — one logical change per PR
  3. Run quality gates (below)
  4. Open a pull request to dev
  5. Address review feedback — keep the PR small and reviewable
git checkout dev
git pull
git checkout -b feat/my-change
# … work …
git commit -m "feat: …"
git push -u origin feat/my-change

Quality Gates

Tool Command Where
Ruff (lint + format) ruff check . && ruff format . Backend / services
pytest pytest Backend (config in pytest.ini)
Frontend typecheck pnpm exec tsc --noEmit admin/
Frontend lint pnpm lint admin/
MkDocs build mkdocs build Docs

All gates must pass before requesting review.

Commit Style

We follow Conventional Commits:

feat: add P1 alert escalation rules
fix: honor rate limit on login endpoint
docs: expand pipeline documentation
refactor: extract canonical event mapping
test: cover dedup window edge cases

Types: feat, fix, docs, refactor, test, chore, style, perf.

Code Conventions

Backend / Services (Python)

  • Type hints on every public function
  • pydantic-settings for config; structlog for logging (component names)
  • Errors use the shared envelope (message, code, details)
  • Alembic migration for any schema change (see Migrations)

Frontend (TypeScript)

  • Components typed strictly; shared UI in components/, feature UI in features/
  • TanStack Query for server state, Zustand for client state
  • Colors via theme.css variables, never hard-coded hex

Docs

  • Pages under docs/ mapped in mkdocs.yml nav
  • One topic per page; tables + mermaid for structure
  • Keep canonical-event / schema docs in sync with code

Testing Guidelines

Area Approach
Backend pytest unit tests for routers/services/errors
Pipeline Fixtures for canonical events; test each stage
Frontend Vitest + React Testing Library for key components
Integration docker compose up + smoke via tests/

New features must include or update tests.

Documentation

  • Update docs/ for any user-facing change
  • Update the Changelog with a summary entry
  • Run mkdocs build to validate nav and links

Getting Help

  • Open an issue for bugs or feature requests
  • Tag reviewers on the PR for questions
  • Reference the Glossary for terminology