Contributing

Contributing

Thank you for your interest in contributing to ApiArk! This guide will help you get set up and make your first contribution.

---

Code of Conduct

Be respectful. Be constructive. We're all here to build great software.

---

Getting Started

Prerequisites

Tool	Version	Purpose
Node.js	22+	Frontend build
pnpm	10+	Package manager
Rust	Latest stable	Backend
Git	2.x+	Version control

Development Setup

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/apiark.git
cd apiark

# 2. Install dependencies
pnpm install

# 3. Install Linux dependencies (Ubuntu/Debian only)
sudo apt install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf libssl-dev

# 4. Start development mode
pnpm dev

This launches:

• Vite dev server (hot-reload for frontend)
• Tauri dev process (rebuilds Rust on changes)
• Opens the app window

Project Structure

apiark/
├── apps/
│   ├── desktop/              # Tauri desktop app
│   │   ├── src/              # React frontend
│   │   │   ├── components/   # UI components
│   │   │   ├── stores/       # Zustand state stores
│   │   │   ├── hooks/        # Custom React hooks
│   │   │   ├── lib/          # Utility functions
│   │   │   ├── types/        # TypeScript types
│   │   │   └── locales/      # i18n translations
│   │   └── src-tauri/        # Rust backend
│   │       └── src/
│   │           ├── commands/  # Tauri IPC handlers
│   │           ├── http/      # HTTP engine
│   │           ├── storage/   # File system + SQLite
│   │           └── models/    # Data models
│   └── cli/                  # CLI tool (Rust)
└── packages/
    ├── types/                # Shared TypeScript types
    └── importer/             # Collection importers

---

How to Contribute

Bug Reports

1. Search existing issues to avoid duplicates
2. Open a new issue with:
   • OS and version
   • ApiArk version
   • Steps to reproduce
   • Expected vs actual behavior
   • Logs from ~/.apiark/logs/apiark.log (if relevant)

Feature Requests

1. Check Discussions — your idea might already be proposed
2. Open a Discussion (not an Issue) with:
   • The problem you're trying to solve
   • Your proposed solution
   • Alternatives you've considered

Code Contributions

1. Find an issue: Look for good first issue or help wanted labels
2. Comment: Let us know you're working on it
3. Branch: Create a branch from main: git checkout -b feat/my-feature
4. Code: Make your changes
5. Test: Ensure everything works
6. PR: Open a pull request

---

Code Standards

Rust

• Format with rustfmt (default settings)
• Lint with clippy at warn level
• Use thiserror for typed errors, anyhow at application boundary
• All Tauri commands return Result<T, String>
• Async by default (tokio)

// Good
#[tauri::command]
async fn get_users(state: State<'_, AppState>) -> Result<Vec<User>, String> {
    state.storage.get_users().await.map_err(|e| e.to_string())
}

// Bad — synchronous, unwrap
#[tauri::command]
fn get_users(state: State<'_, AppState>) -> Vec<User> {
    state.storage.get_users().unwrap()
}

TypeScript / React

• ESLint + Prettier for formatting
• Functional components only
• Zustand for state management
• No any unless absolutely necessary
• File naming: kebab-case.tsx for components, camelCase.ts for utilities
• Component naming: PascalCase, one component per file

// Good
export function RequestBuilder({ request, onSend }: RequestBuilderProps) {
  const { activeEnvironment } = useEnvironmentStore();
  // ...
}

// Bad — class component, inline styles, any
export class RequestBuilder extends React.Component<any> {
  render() {
    return <div style={{color: 'red'}}>...</div>
  }
}

Git Conventions

Branch naming:

• feat/description — New features
• fix/description — Bug fixes
• refactor/description — Code refactoring
• docs/description — Documentation

Commit messages (Conventional Commits):

feat: add GraphQL schema explorer
fix: resolve WebSocket connection cleanup
refactor: extract auth module from http client
docs: add contributing guide
test: add collection runner tests
chore: bump dependencies

---

Pull Request Process

1. Title: Short, descriptive (e.g., "feat: add gRPC server reflection support")
2. Description: What changed and why. Link the issue it addresses
3. Size: Keep PRs small and focused. One feature/fix per PR
4. Tests: Add tests for new functionality
5. No breaking changes without discussion first
6. CI must pass: All checks must be green

PR Template

## Summary
Brief description of what this PR does.

## Changes
- Added X
- Fixed Y
- Refactored Z

## Test Plan
- [ ] Tested manually on [OS]
- [ ] Added unit tests
- [ ] Existing tests pass

Closes #123

---

Translations

Help translate ApiArk to your language:

1. Copy apps/desktop/src/locales/en.json
2. Create apps/desktop/src/locales/{language-code}.json
3. Translate all strings
4. Open a PR

Current translations: English, Spanish, French, German, Portuguese, Chinese, Japanese, Korean, Arabic.

---

Architecture Overview

Frontend (React + TypeScript)
    │
    │ Tauri IPC (invoke commands)
    │
Backend (Rust)
    ├── HTTP Engine (reqwest)
    ├── File System (tokio fs)
    ├── Script Engine (rquickjs)
    ├── Mock Server (axum)
    ├── gRPC Client (tonic)
    ├── WebSocket Client (tokio-tungstenite)
    └── Database (rusqlite/SQLite)

Key design decisions:

• Tauri v2: Native performance, small binary, OS-level webview
• Zustand: Simple state management without boilerplate
• YAML on filesystem: Git-native, no migration headaches
• SQLite: Only for ephemeral data (history, monitors) — never for user collections

---

Need Help?

• GitHub Discussions — Ask questions
• Discord — Real-time chat with the team
• Read CLAUDE.md in the repo root — comprehensive technical documentation