Developer Guide

This guide covers the day-to-day workflows for contributing to Audra Flow: how branches are managed, where code lives, how to write and run tests, and how pull requests move through review.

Git Branching Strategy

Audra Flow follows the Git Flow branching model with two long-lived branches and three types of short-lived branches.

Long-Lived Branches

Short-Lived Branches

Typical Feature Workflow

# 1. Start from an up-to-date develop branch
git checkout develop
git pull origin develop

# 2. Create your feature branch
git checkout -b feature/TICKET-123-add-persona-editor

# 3. Make changes and commit
git add .
git commit -m "feat(TICKET-123): add persona editor component"

# 4. Push and open a PR to develop
git push -u origin feature/TICKET-123-add-persona-editor

Code Structure Quick Reference

Use this table to find the right directory when adding or modifying code:

Testing Strategy

Audra Flow uses a multi-layer testing approach across all services:

Frontend Tests (Vitest)

Unit and component tests for the React frontend are written with Vitest. Tests live alongside the source files or in dedicated __tests__ directories.

# Run frontend unit tests
cd apps/web
npm run test

End-to-End Tests (Playwright)

E2E tests exercise the full stack from browser to database. They run against a Docker Compose environment.

# Run E2E tests
npm run test:e2e

AI Service Tests (Pytest)

The Python AI service uses Pytest with fixtures for mocking LLM calls and vector store interactions.

# Run AI service tests
cd apps/ai-service
poetry run pytest

Test Coverage Expectations

Pull Request Workflow

Every change goes through a pull request before it reaches develop or main. Here is the expected flow:

1. Open a PR from your feature branch to develop. Include a clear description of what changed and why.
2. Automated checks run — linting (ESLint, Ruff), type checking (TypeScript, Pyright), unit tests, and build verification.
3. Code review — at least one team member reviews the changes.
4. Address feedback — push additional commits to the same branch. Avoid force-pushing over reviewed commits.
5. Merge — once approved and all checks pass, merge with a merge commit (--no-ff). Delete the feature branch after merge.

Commit Message Convention

The project uses Conventional Commits to keep history readable and enable automated changelog generation.

type(scope): short description

# Examples:
feat(discovery): add competitor analysis view
fix(auth): resolve token refresh race condition
docs: update API reference for templates endpoint
refactor(prisma): simplify approval workflow queries
test(guru): add unit tests for gap analysis agent

Commit Types

Coding Conventions

TypeScript (Frontend & Backend)

• Use strict mode in all tsconfig.json files.
• Prefer interface over type for object shapes. Use type for unions and intersections.
• All API request and response shapes must have corresponding Zod schemas in packages/validation.
• Use named exports. Avoid default exports except for page components.
• Follow the ESLint configuration included in the repo — run npm run lint before committing.

Python (AI Service)

• Follow PEP 8 and format code with Ruff.
• Use Pydantic models for all request/response validation.
• Type-hint all function parameters and return values.
• Keep business logic in services/ and route handling in api/routes/.

General

• Keep functions small and focused — aim for a single responsibility per function.
• Write descriptive variable names. Avoid abbreviations except for well-known terms (e.g. id, url, ctx).
• Always use --no-ff merges to preserve branch history in the commit graph.
• Delete feature branches after they are merged.

CI/CD Pipeline

Every push and pull request triggers the CI pipeline in GitHub Actions:

Next Steps

• Quick Start — set up your local environment.
• System Architecture — understand the overall system design.
• API Reference — explore endpoints for every resource.