# Contributing to pi-gateway

Thank you for your interest in contributing to pi-gateway! This document provides guidelines and instructions for contributing.

## Development Setup

### Prerequisites

- [Bun](https://bun.sh) >= 1.1.0
- [Node.js](https://nodejs.org) >= 18 (for tooling)
- Git

### Getting Started

```bash
# Clone the repository
git clone https://github.com/openclaw/pi-gateway.git
cd pi-gateway

# Install dependencies
bun install

# Install admin console dependencies
bun run admin:install

# Start development server
bun run dev
```

### Project Structure

```
pi-gateway/
├── src/
│   ├── cli.ts           # CLI entry point
│   ├── server.ts        # Gateway core
│   ├── core/            # Core modules (config, rpc, session, cron)
│   ├── plugins/         # Plugin system
│   ├── security/        # Authentication and authorization
│   └── web/             # Web UI (Lit components)
├── admin-console/       # Admin dashboard (Vite + Vue)
├── docs/                # Documentation
└── tests/               # Test files
```

## Code Style

### TypeScript

- Use TypeScript strict mode
- Prefer `interface` over `type` for object shapes
- Use explicit return types for public functions
- Document public APIs with JSDoc comments

### Code Organization

- One module per file
- Keep files focused on a single responsibility
- Use barrel exports (`index.ts`) for module public API
- Follow existing naming conventions

### Commits

- Use conventional commit format:
  - `feat: add new feature`
  - `fix: resolve bug`
  - `docs: update documentation`
  - `refactor: improve code structure`
  - `test: add tests`
  - `chore: maintenance tasks`

## Testing

```bash
# Run type checking
bun run check

# Run tests (when available)
bun test
```

## Pull Request Process

1. **Fork and Branch**
   - Fork the repository
   - Create a feature branch from `main`
   - Use descriptive branch names (e.g., `feat/telegram-webhooks`, `fix/rpc-pool-crash`)

2. **Make Changes**
   - Write clear, well-documented code
   - Add tests for new functionality
   - Update documentation as needed

3. **Submit PR**
   - Fill out the PR template completely
   - Link related issues
   - Request review from maintainers

4. **Review Process**
   - Address review feedback promptly
   - Keep PRs focused and reasonably sized
   - Maintain a clean git history

### PR Checklist

- [ ] Code compiles without errors (`bun run check`)
- [ ] Tests pass (if applicable)
- [ ] Documentation updated (if applicable)
- [ ] Commit messages follow conventional format
- [ ] PR description clearly explains changes

## Reporting Issues

### Bug Reports

Use the bug report template and include:

- Environment details (OS, Bun version)
- Steps to reproduce
- Expected behavior
- Actual behavior
- Relevant logs

### Feature Requests

Use the feature request template and include:

- Clear description of the feature
- Use case and motivation
- Possible implementation approach (optional)

## Development Tips

### Debugging

```bash
# Run with verbose logging
bun run src/cli.ts gateway --verbose

# Check gateway health
bun run src/cli.ts doctor
```

### Hot Reload

The development server (`bun run dev`) automatically reloads on file changes.

### Plugin Development

See `docs/architecture/PLUGINS-AND-CHANNELS.md` for plugin development guide.

## License

By contributing, you agree that your contributions will be licensed under the MIT License.

## Questions?

- Open a [Discussion](https://github.com/openclaw/pi-gateway/discussions) for questions
- Join our community (link TBD)

---

Thank you for contributing to pi-gateway! 🚀