Skip to content

Software Quality

Jump to bottom
Nicolas Rico edited this page Mar 24, 2026 · 2 revisions

Table of Contents

1. Naming Standards

Sentinel follows the official naming conventions of each language and framework used. The goal is to maintain readable, consistent, and predictable code across the full stack.

1.1 Python (Backend)

The backend follows PEP 8 — the official Python style guide — as the naming standard.

Element Convention Example
Variables snake_case container_name, incident_id
Functions snake_case process_prometheus_alert(), query_loki_logs()
Classes PascalCase IncidentCreate, IncidentState
Constants UPPER_SNAKE_CASE SEVERITY_MAP, LOKI_URL
Modules / files snake_case alert_processor.py, supabase_client.py
Private functions _snake_case (leading underscore) _resolve_incident(), _get_llm()

Reference: PEP 8 — Style Guide for Python Code

1.2 JavaScript / React (Frontend)

The frontend follows the Airbnb JavaScript Style Guide and the official React component naming conventions.

Element Convention Example
Variables and functions camelCase fetchIncidents, handleSignOut
React components PascalCase Dashboard, SeverityBadge, MetaCard
Component files PascalCase.jsx Dashboard.jsx, Login.jsx
Constants (config objects) UPPER_SNAKE_CASE SEVERITY_CONFIG, STATUS_CONFIG
CSS / Tailwind Utility classes only bg-red-500, text-slate-400

References:

1.3 Git

Element Convention Example
Branch names type/short-description (kebab-case) feature/backend-env-setup, fix/container-name-label
Commit messages Conventional Commits (type: description) feat: add LangGraph Labs 1 and 2, fix: extract container name from cAdvisor label

References:

2. Static Code Analysis

2.1 Python — Ruff

The backend uses Ruff as the primary static analysis and formatting tool. Ruff is a high-performance Python linter written in Rust that consolidates the functionality of flake8, isort, and black into a single tool.

Justification:

  • Replaces flake8 + black + isort with a single dependency
  • Significantly faster than traditional tools (10–100x)
  • Enforces PEP 8 naming conventions and detects common errors
  • Supports auto-fix for formatting violations (ruff format)
  • Actively maintained and recommended by the Python community

Configuration: Backend/pyproject.toml

[tool.ruff]
line-length = 100
target-version = "py39"

[tool.ruff.lint]
select = ["E", "F", "I", "N", "W"]
# E: pycodestyle errors
# F: Pyflakes (undefined names, unused imports)
# I: isort (import ordering)
# N: pep8-naming (naming conventions)
# W: pycodestyle warnings

Usage:

cd Backend
ruff check .          # Run linter
ruff check . --fix    # Auto-fix safe issues
ruff format .         # Format code (replaces black)

2.2 JavaScript / React — ESLint

The frontend uses ESLint with the recommended React and hooks plugins.

Justification:

  • Official standard for JavaScript/React static analysis
  • Catches common React mistakes (missing keys, hooks rule violations)
  • Integrated with Vite's build process
  • Configuration is extensible and widely documented

Configuration: Frontend/eslint.config.js (already present in the project)

import js from '@eslint/js'
import reactHooks from 'eslint-plugin-react-hooks'
import reactRefresh from 'eslint-plugin-react-refresh'

export default [
  js.configs.recommended,
  {
    plugins: { 'react-hooks': reactHooks, 'react-refresh': reactRefresh },
    rules: {
      ...reactHooks.configs.recommended.rules,
      'react-refresh/only-export-components': 'warn',
    },
  },
]

Usage:

cd Frontend
npm run lint          # Run ESLint

3. Branching Strategy

Sentinel uses GitHub Flow as the branching strategy.

Justification:

  • Simple and suitable for small teams (6 developers)
  • main is always deployable
  • Every new feature or fix is developed on a dedicated branch
  • Changes reach main exclusively through Pull Requests with peer review

Branch naming convention:

Type Pattern Example
Feature feature/<description> feature/langgraph-labs
Bug fix fix/<description> fix/container-name-label
Documentation docs/<description> docs/wiki-quality-page
Configuration chore/<description> chore/add-ruff-config

Workflow:

main (always stable)
  └── feature/new-feature    ← develop here
        └── Pull Request → peer review → merge to main

Reference: GitHub Flow

4. Continuous Integration Pipeline

📅 Status: Planned for Sprint 2.

The project will use GitHub Actions to automate quality checks on every Pull Request targeting main.

Pipeline goals:

  • Block merges until linting passes (ruff + ESLint)
  • Require at least one peer approval before merging
  • Auto-deploy documentation on merge to main

Workflow file: .github/workflows/ci.yml (Sprint 2)

Planned steps:

on:
  pull_request:
    branches: [main]

jobs:
  lint-backend:
    - Install Python dependencies
    - Run: ruff check Backend/

  lint-frontend:
    - Install Node dependencies
    - Run: npm run lint (ESLint)

Clone this wiki locally