Coding Standards & Development Guidelines

Comprehensive development standards ensuring consistent code quality, maintainable architecture, and streamlined collaboration across the ReptiDex engineering team.

Jira Standards

Ticket naming & tracking

Git Workflow

Branching & commits

Code Standards

Language-specific guidelines

Review Process

PR standards & reviews

Jira Integration & Ticket Standards

Ticket Naming Conventions

Service-Scoped Tasks

Sub-tasks must include service prefix

Format: {service}: {action description}
Examples: repti-core: set up auth, repti-animal: add pedigree tracking
Enables easy filtering and service ownership clarity

Cross-Service Tasks

Multi-service coordination

Format: multi-service: {description} or integration: {description}
Examples: integration: connect animal service to marketplace
Use when changes span multiple services

Ticket Structure Standards

Epic Naming
Story Naming
Sub-task Naming
Bug & Task Naming

Epic Title Format

{Business Capability} - {Version/Phase}

Examples:
✅ Core Authentication & User Management - MVP
✅ Advanced Breeding Management - Phase 2
✅ Marketplace Integration - V1.2

❌ User authentication
❌ Add breeding features

Epic Description Template:

## Business Objective
Brief description of the business value and user impact.

## Success Criteria
- [ ] Measurable outcome 1
- [ ] Measurable outcome 2

## Technical Scope
- Services involved: repti-core, repti-animal
- External integrations: Stripe, AWS KMS

## Dependencies
- Blocks/Blocked by: [Epic links]

## Acceptance Criteria
High-level acceptance criteria for the entire epic

Jira Ticket Lifecycle

Standard Ticket Workflow

• Product Scoped: Product Requirements Defined
• Engineering Scoped: Engineering scoped and ready for work
• Ready for Work: Requirements defined, ready for development

• In Progress: Active development
• In Review: PR submitted and under review
• QA: QA validation in progress

• Done: Deployed to production
• Blocked: Waiting on dependency
• Cancelled: No longer needed

Git Workflow & Branch Management

Branch Naming Strategy

Feature Branches
Hotfix & Release Branches
Branch Protection Rules

Feature Branch Format

feature/{JIRA-ID}-{brief-description}

Examples:
✅ feature/REPTI-123-user-authentication
✅ feature/REPTI-456-animal-registration-form  
✅ feature/REPTI-789-stripe-payment-integration

# For sub-tasks, include service prefix
✅ feature/REPTI-123-repti-core-jwt-middleware
✅ feature/REPTI-456-frontend-registration-form

❌ feature/auth-stuff
❌ feature/new-feature
❌ john-working-branch

Branch Creation:

# Create feature branch from main
git checkout main
git pull origin main
git checkout -b feature/REPTI-123-user-authentication

# Push and set upstream
git push -u origin feature/REPTI-123-user-authentication

Commit Message Standards

Conventional Commits Format

[optional body]
[optional footer(s)]

Commit Types
Commit Examples
Jira Integration

Standard Commit Types

Type	Description	Example
`feat`	New feature	`feat(repti-core): add JWT authentication middleware`
`fix`	Bug fix	`fix(repti-animal): resolve pedigree tree loading issue`
`docs`	Documentation	`docs(api): update authentication endpoint documentation`
`style`	Code style changes	`style(frontend): fix ESLint formatting issues`
`refactor`	Code refactoring	`refactor(repti-commerce): simplify payment processing logic`
`perf`	Performance improvement	`perf(database): optimize animal query with indexes`
`test`	Testing changes	`test(repti-core): add integration tests for auth service`
`build`	Build system changes	`build(docker): update Node.js to version 18`
`ci`	CI/CD changes	`ci(github): add automated security scanning`
`chore`	Maintenance tasks	`chore(deps): update dependencies to latest versions`

Commit Scopes (Service Names)

repti-core, repti-animal, repti-commerce, repti-community, repti-media, repti-ops
frontend, database, infrastructure, docs, testing

Language-Specific Code Standards

Python (FastAPI Services)

Style & Formatting
Code Structure
API Standards
Testing Standards

Code Formatting Standards

Required Tools:

# Install formatting and linting tools
pip install black isort flake8 mypy pre-commit

# Pre-commit configuration
pre-commit install

Black Configuration (pyproject.toml):

[tool.black]
line-length = 88
target-version = ['py311']
include = '\.pyi?$'
extend-exclude = '''
/(
  # Exclude auto-generated files
  migrations
  | __pycache__
  | .git
  | .venv
)/
'''

Import Sorting (isort):

[tool.isort]
profile = "black"
multi_line_output = 3
line_length = 88
known_first_party = ["app"]
sections = ["FUTURE", "STDLIB", "THIRDPARTY", "FIRSTPARTY", "LOCALFOLDER"]

Flake8 Configuration (.flake8):

[flake8]
max-line-length = 88
extend-ignore = E203, W503, E501
exclude = 
    .git,
    __pycache__,
    migrations,
    .venv

TypeScript/React (Frontend)

TypeScript Configuration
React Component Standards
State Management
Testing Standards

TypeScript Standards

tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["dom", "dom.iterable", "es6"],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noFallthroughCasesInSwitch": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "baseUrl": "src",
    "paths": {
      "@/*": ["*"],
      "@/components/*": ["components/*"],
      "@/services/*": ["services/*"],
      "@/utils/*": ["utils/*"]
    }
  },
  "include": ["src", "types"],
  "exclude": ["node_modules", "build", "dist"]
}

ESLint Configuration:

{
  "extends": [
    "react-app",
    "react-app/jest",
    "@typescript-eslint/recommended",
    "prettier"
  ],
  "rules": {
    "@typescript-eslint/no-unused-vars": "error",
    "@typescript-eslint/no-explicit-any": "warn",
    "react/jsx-props-no-spreading": "off",
    "import/order": [
      "error",
      {
        "groups": [
          "builtin",
          "external",
          "internal",
          "parent",
          "sibling",
          "index"
        ],
        "newlines-between": "always"
      }
    ]
  }
}

SQL & Database Standards

Schema Design
Migration Standards
Query Standards

Database Naming Conventions

Table Names:

-- Use plural nouns, snake_case
✅ users
✅ animal_records  
✅ breeding_events
✅ marketplace_listings

❌ User
❌ animalRecord
❌ BreedingEvent

Column Names:

-- Use snake_case, descriptive names
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    username VARCHAR(50) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    email_verified BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW(),
    deleted_at TIMESTAMPTZ  -- Soft delete pattern
);

-- Foreign key naming: {referenced_table}_id
CREATE TABLE animal_records (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    owner_id UUID REFERENCES users(id),
    species_id UUID REFERENCES species(id),
    -- ...
);

Index Naming:

-- Format: idx_{table}_{column(s)}
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_username ON users(username);
CREATE INDEX idx_animal_records_owner ON animal_records(owner_id);
CREATE INDEX idx_animal_records_species_created ON animal_records(species_id, created_at);

-- Unique indexes: unq_{table}_{column(s)}
CREATE UNIQUE INDEX unq_users_email ON users(email);

Pull Request & Code Review Process

Pull Request Standards

PR Title Format

<type>(<service>): <brief description> [REPTI-###]

PR Templates
Review Guidelines
Approval Workflow
Automation & Quality Gates

Pull Request Template

GitHub PR Template (.github/pull_request_template.md):

## 📝 Summary
Brief description of changes made in this PR.

## 🎫 Jira Ticket
- **Ticket**: [REPTI-XXX](https://reptidex.atlassian.net/browse/REPTI-XXX)
- **Type**: Feature/Bug Fix/Refactor/Documentation

## 🔧 Changes Made
- [ ] List specific changes
- [ ] Include technical details
- [ ] Mention any breaking changes

## 🧪 Testing
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Manual testing completed
- [ ] All existing tests pass

## 📋 Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No sensitive data exposed
- [ ] Database migrations included (if applicable)

## 🎯 Review Focus Areas
Specific areas where you want reviewer attention:
- Performance considerations
- Security implications
- API design decisions

## 📸 Screenshots/Videos
Include screenshots for UI changes or videos for complex workflows.

## 🔗 Related PRs
Link any related or dependent pull requests.

Hotfix PR Template

## 🚨 HOTFIX: Critical Issue Resolution

**Urgency Level**: Critical/High/Medium
**Affected Environment**: Production/Staging

## 🐛 Issue Description
Detailed description of the critical issue being fixed.

## 🎫 Jira Ticket
- **Ticket**: [REPTI-XXX](https://reptidex.atlassian.net/browse/REPTI-XXX)
- **Incident**: [Link to incident report]

## 🔧 Root Cause
Technical explanation of what caused the issue.

## ✅ Solution
Detailed explanation of the fix implemented.

## 🧪 Testing
- [ ] Fix verified in staging
- [ ] Regression tests added
- [ ] Impact on related features tested

## 📊 Deployment Plan
- [ ] Database changes: Yes/No
- [ ] Requires restart: Yes/No
- [ ] Rollback plan documented

Development Workflow Summary

Daily Development Workflow

Complete Development Cycle

Create properly formatted ticket with service prefix: “repti-core: implement JWT authentication”

Create feature branch: “feature/REPTI-123-repti-core-jwt-middleware”

Make commits with conventional format: “feat(repti-core): add JWT validation middleware”

Create PR with template: “feat(repti-core): implement JWT authentication middleware [REPTI-123]“

Address feedback, get approvals, merge with squash commit

Automatic ticket transition to Done, deployment tracking

Quick Reference Commands

# Create and switch to feature branch
git checkout -b feature/REPTI-123-repti-core-auth-middleware

# Make conventional commit
git commit -m "feat(repti-core): add JWT validation middleware

- Implement token verification for protected routes
- Add comprehensive error handling
- Include refresh token logic

Closes: REPTI-123"

# Push and create PR
git push -u origin feature/REPTI-123-repti-core-auth-middleware
gh pr create --title "feat(repti-core): implement JWT authentication middleware [REPTI-123]" --body-file .github/pull_request_template.md

These coding standards ensure consistent, high-quality code across the reptidex platform while maintaining clear traceability between Jira tickets, git branches, commits, and pull requests. Regular updates to these standards will be made as the team grows and best practices evolve.

Getting Started

System Architecture

Backend Services

Frontend Applications

Shared Packages

Development Standards

Infrastructure & Operations

API Reference

​Coding Standards & Development Guidelines

​Quick Navigation

​Jira Integration & Ticket Standards

​Ticket Naming Conventions

Service-Scoped Tasks

Cross-Service Tasks

​Ticket Structure Standards

​Epic Title Format

​Jira Ticket Lifecycle

​Standard Ticket Workflow

​Git Workflow & Branch Management

​Branch Naming Strategy

​Feature Branch Format

​Commit Message Standards

​Conventional Commits Format

​Standard Commit Types

​Commit Scopes (Service Names)

​Language-Specific Code Standards

​Python (FastAPI Services)

​Code Formatting Standards

​TypeScript/React (Frontend)

​TypeScript Standards

​SQL & Database Standards

​Database Naming Conventions

​Pull Request & Code Review Process

​Pull Request Standards

​PR Title Format

​Pull Request Template

​Hotfix PR Template

​Development Workflow Summary

​Daily Development Workflow

​Complete Development Cycle

​Quick Reference Commands

Coding Standards & Development Guidelines

Quick Navigation

Jira Integration & Ticket Standards

Ticket Naming Conventions

Ticket Structure Standards

Epic Title Format

Jira Ticket Lifecycle

Standard Ticket Workflow

Git Workflow & Branch Management

Branch Naming Strategy

Feature Branch Format

Commit Message Standards

Conventional Commits Format

Standard Commit Types

Commit Scopes (Service Names)

Language-Specific Code Standards

Python (FastAPI Services)

Code Formatting Standards

TypeScript/React (Frontend)

TypeScript Standards

SQL & Database Standards

Database Naming Conventions

Pull Request & Code Review Process

Pull Request Standards

PR Title Format

Pull Request Template

Hotfix PR Template

Development Workflow Summary

Daily Development Workflow

Complete Development Cycle

Quick Reference Commands