Contributing to CODITECT Document Management System

Thank you for your interest in contributing to the CODITECT Enterprise Content and Document Management System! This document provides guidelines and workflows for contributing to the project.

Table of Contents

1. Code of Conduct
2. Development Workflow
3. Code Standards
4. Testing Requirements
5. Pull Request Process
6. Code Review Guidelines
7. Documentation Standards

---

Code of Conduct

This project adheres to the CODITECT Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to support@az1.ai.

Key Principles:

• Be respectful and inclusive
• Focus on constructive feedback
• Assume good faith
• Maintain professional communication

---

Development Workflow

1. Fork and Clone

# Fork the repository on GitHub
# Clone your fork
git clone https://github.com/YOUR_USERNAME/coditect-rollout-master.git
cd coditect-rollout-master/submodules/ops/coditect-document-management

# Add upstream remote
git remote add upstream https://github.com/coditect-ai/coditect-rollout-master.git

2. Create Feature Branch

# Ensure main is up to date
git checkout main
git pull upstream main

# Create feature branch
git checkout -b feature/your-feature-name

# Or for bug fixes
git checkout -b fix/bug-description

3. Development Setup

# Install dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt
npm run install:all

# Set up environment
cp .env.example .env
# Edit .env with development credentials

4. Make Changes

• Write clean, documented code
• Follow code standards (see below)
• Add tests for new features
• Update documentation as needed

5. Test Your Changes

# Run all tests
npm run test:all

# Backend tests only
npm run backend:test

# Frontend tests only
npm run test:frontend

# Check coverage
pytest --cov=src/backend --cov-report=html

6. Commit Changes

# Stage changes
git add .

# Commit with conventional commit format
git commit -m "feat: Add semantic search endpoint

- Implement vector-based search using pgvector
- Add cosine similarity ranking
- Include pagination support
- Update API documentation

Closes #123"

7. Push and Create Pull Request

# Push to your fork
git push origin feature/your-feature-name

# Open Pull Request on GitHub
# Fill out the PR template completely

---

Code Standards

Python (Backend)

Style Guide: PEP 8

Requirements:

• Type hints for all function parameters and return values
• Docstrings for all public functions, classes, and modules (Google style)
• Maximum line length: 88 characters (Black formatter)
• Import organization: stdlib, third-party, local (isort)

Example:

from typing import List, Optional

from fastapi import APIRouter, HTTPException
from pydantic import BaseModel

from src.backend.database.operations import DocumentRepository


class DocumentSearchRequest(BaseModel):
    """Request model for document search.

    Attributes:
        query: Search query string.
        limit: Maximum number of results to return.
        offset: Number of results to skip for pagination.
    """
    query: str
    limit: int = 10
    offset: int = 0


async def search_documents(
    request: DocumentSearchRequest,
    repository: DocumentRepository,
) -> List[Document]:
    """Search documents using semantic vector search.

    Args:
        request: Search request parameters.
        repository: Document repository instance.

    Returns:
        List of matching documents sorted by relevance.

    Raises:
        HTTPException: If search fails or query is invalid.
    """
    if not request.query.strip():
        raise HTTPException(status_code=400, detail="Query cannot be empty")

    return await repository.vector_search(
        query=request.query,
        limit=request.limit,
        offset=request.offset,
    )

Linting and Formatting:

# Format code with Black
black src/backend tests/backend

# Sort imports with isort
isort src/backend tests/backend

# Run linters
flake8 src/backend
mypy src/backend
pylint src/backend

TypeScript/React (Frontend)

Style Guide: ESLint + Prettier

Requirements:

• TypeScript strict mode enabled
• Functional components with hooks
• Props interface for all components
• Component documentation with JSDoc
• CSS modules or Tailwind for styling

Example:

import React, { useState, useEffect } from 'react';

interface DocumentSearchProps {
  /** Callback when search is performed */
  onSearch: (query: string) => void;
  /** Initial query value */
  initialQuery?: string;
  /** Whether search is loading */
  isLoading?: boolean;
}

/**
 * Document search input component.
 *
 * Provides a search interface with debouncing and validation.
 *
 * @param props - Component props
 * @returns Rendered search input
 */
export const DocumentSearch: React.FC<DocumentSearchProps> = ({
  onSearch,
  initialQuery = '',
  isLoading = false,
}) => {
  const [query, setQuery] = useState(initialQuery);

  useEffect(() => {
    const timer = setTimeout(() => {
      if (query.trim()) {
        onSearch(query);
      }
    }, 300);

    return () => clearTimeout(timer);
  }, [query, onSearch]);

  return (
    <input
      type="text"
      value={query}
      onChange={(e) => setQuery(e.target.value)}
      disabled={isLoading}
      placeholder="Search documents..."
      className="w-full px-4 py-2 border rounded"
    />
  );
};

Linting and Formatting:

# Lint and fix
npm run lint:frontend

# Type check
cd src/frontend && npm run type-check

# Format with Prettier
cd src/frontend && npm run format

---

Testing Requirements

Coverage Requirements

• Minimum 80% code coverage for new code
• 100% coverage for security-critical code
• All public APIs must have tests

Backend Testing

Test Structure:

tests/backend/
├── conftest.py              # Pytest fixtures
├── test_security/           # Security tests
│   ├── test_jwt_service.py
│   └── test_rbac.py
├── test_database/           # Database tests
└── test_api/                # API endpoint tests

Example Test:

import pytest
from fastapi.testclient import TestClient

from src.backend.main import app


@pytest.fixture
def client():
    """Create test client."""
    return TestClient(app)


def test_search_documents_success(client):
    """Test successful document search."""
    response = client.post(
        "/documents/search",
        json={"query": "test document", "limit": 10},
    )

    assert response.status_code == 200
    data = response.json()
    assert isinstance(data, list)
    assert len(data) <= 10


def test_search_documents_empty_query(client):
    """Test search with empty query returns 400."""
    response = client.post(
        "/documents/search",
        json={"query": "", "limit": 10},
    )

    assert response.status_code == 400

Frontend Testing

Test Structure:

src/frontend/components/
└── DocumentSearch/
    ├── DocumentSearch.tsx
    └── DocumentSearch.test.tsx

Example Test:

import { render, screen, fireEvent, waitFor } from '@testing-library/react';
import { DocumentSearch } from './DocumentSearch';

describe('DocumentSearch', () => {
  it('renders search input', () => {
    const onSearch = jest.fn();
    render(<DocumentSearch onSearch={onSearch} />);

    expect(screen.getByPlaceholderText('Search documents...')).toBeInTheDocument();
  });

  it('calls onSearch after debounce delay', async () => {
    const onSearch = jest.fn();
    render(<DocumentSearch onSearch={onSearch} />);

    const input = screen.getByPlaceholderText('Search documents...');
    fireEvent.change(input, { target: { value: 'test query' } });

    await waitFor(() => {
      expect(onSearch).toHaveBeenCalledWith('test query');
    }, { timeout: 500 });
  });
});

---

Pull Request Process

1. Before Submitting

• Code follows style guidelines
• All tests pass locally
• Test coverage meets requirements (80%+)
• Documentation is updated
• Commit messages follow conventional commits
• No merge conflicts with main

2. PR Template

Fill out the PR template completely:

## Description
[Clear description of changes]

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
[How you tested the changes]

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Follows code standards
- [ ] No breaking changes (or documented)

3. Review Process

• PRs require at least 1 approval
• All CI checks must pass
• Maintainer review required for architecture changes
• Address all review comments

4. After Approval

• Squash commits if needed
• Maintainer will merge when ready
• Delete feature branch after merge

---

Code Review Guidelines

For Authors

• Keep PRs focused and reasonably sized (<500 lines)
• Respond to feedback constructively
• Be willing to iterate on design
• Update PR description as changes evolve

For Reviewers

• Review within 2 business days
• Focus on code quality, not style (automated)
• Suggest, don't dictate
• Approve when ready, request changes if needed

Review Checklist:

• Code is clear and maintainable
• Tests cover new functionality
• No security vulnerabilities introduced
• Performance impact is acceptable
• Documentation is adequate
• Follows project architecture

---

Documentation Standards

Code Documentation

• All public APIs documented with docstrings/JSDoc
• Complex logic explained with inline comments
• README updated for new features

Architecture Documentation

• Update docs/01-architecture/ for architectural changes
• Add ADRs for significant decisions
• Update diagrams when structure changes

API Documentation

• OpenAPI/Swagger annotations for all endpoints
• Request/response examples
• Error codes documented

---

Questions?

• Check README.md for project overview
• Review CLAUDE.md for AI agent guidance
• Ask in GitHub Discussions
• Email: support@az1.ai

---

Thank you for contributing to CODITECT Document Management System!

Last Updated: December 19, 2025 Version: 1.0