Skip to content

Commit e48b24c

Browse files
joaquinbejarjoaquinbejar
authored
M4 #39: Developer documentation (#96)
* docs: add comprehensive developer documentation Main README.md: - Project overview and features - Architecture diagram - Quick start guide with code examples - Links to detailed documentation - Contributing guidelines reference - License information Documentation (docs/): - architecture.md: System architecture with diagrams - getting-started.md: Step-by-step integration guide - api-reference.md: Complete REST API documentation - websocket-reference.md: WebSocket API documentation - sdk-guide.md: SDK usage for Rust and TypeScript - faq.md: Frequently asked questions API Documentation: - openapi.yaml: OpenAPI 3.0 specification Project Files: - CHANGELOG.md: Version history - SECURITY.md: Security policy and bug bounty - CONTRIBUTING.md: Contribution guidelines Closes #39 * refactor: move Docker files to Docker/ directory - Move Dockerfiles to Docker/ directory: - api/Dockerfile -> Docker/Dockerfile.api - crank/Dockerfile -> Docker/Dockerfile.crank - indexer/Dockerfile -> Docker/Dockerfile.indexer - .dockerignore -> Docker/.dockerignore (and root copy) - Update references in: - docker-compose.yml - .github/workflows/ci.yml - .github/workflows/release.yml - .github/workflows/security.yml - docs/docker.md This consolidates all Docker-related files in one directory for better organization. * refactor: rename Dockerfiles to use .Dockerfile extension - Rename Docker files: - Docker/Dockerfile.api -> Docker/api.Dockerfile - Docker/Dockerfile.crank -> Docker/crank.Dockerfile - Docker/Dockerfile.indexer -> Docker/indexer.Dockerfile - Update references in: - docker-compose.yml - .github/workflows/ci.yml - .github/workflows/release.yml - .github/workflows/security.yml - docs/docker.md * refactor: move docker-compose files to Docker/ directory - Move docker-compose.yml and docker-compose.prod.yml to Docker/ - Update all paths in docker-compose files to use relative paths from Docker/ - Update documentation references: - README.md - docs/docker.md - docs/monitoring.md - docs/operations/maintenance.md - docs/operations/emergency-procedures.md Docker directory structure: Docker/ ├── .dockerignore ├── api.Dockerfile ├── crank.Dockerfile ├── docker-compose.yml ├── docker-compose.prod.yml └── indexer.Dockerfile * fix: update Rust version in Dockerfiles to 1.85 rust:1.93-bookworm doesn't exist yet, using 1.85 which is available. * feat: add binary entry points for Docker builds Add main.rs files for each service to enable Docker image builds: - api/src/main.rs: API server entry point - indexer/src/main.rs: Indexer service entry point - crank/src/main.rs: Crank service entry point Update Cargo.toml files: - Add [[bin]] targets for each service - Add tracing-subscriber to workspace dependencies - Export ServerConfig from api lib.rs * fix: make dependency-review job optional The dependency-review action requires Dependency graph to be enabled in the repository settings. Adding continue-on-error: true so it doesn't block CI while the feature is not enabled. To enable: https://github.com/joaquinbejar/matchbook/settings/security_analysis * fix: make dependency-review mandatory now that Dependency graph is enabled * fix: specify package in Docker build commands Use -p flag to specify the package when building binaries in workspace: - cargo build --release -p matchbook-api --bin matchbook-api - cargo build --release -p matchbook-indexer --bin matchbook-indexer - cargo build --release -p matchbook-crank --bin matchbook-crank This fixes the 'no bin target named X in default-run packages' error.
1 parent 74eb170 commit e48b24c

32 files changed

Lines changed: 4427 additions & 69 deletions

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -195,7 +195,7 @@ jobs:
195195
uses: docker/build-push-action@v6
196196
with:
197197
context: .
198-
file: ./${{ matrix.service }}/Dockerfile
198+
file: ./Docker/${{ matrix.service }}.Dockerfile
199199
push: false
200200
tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}-${{ matrix.service }}:test
201201
cache-from: type=gha

‎.github/workflows/release.yml‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ name: Release
33
on:
44
push:
55
tags:
6-
- 'v*'
6+
- "v*"
77

88
env:
99
CARGO_TERM_COLOR: always
@@ -77,7 +77,7 @@ jobs:
7777
uses: docker/build-push-action@v6
7878
with:
7979
context: .
80-
file: ./${{ matrix.service }}/Dockerfile
80+
file: ./Docker/${{ matrix.service }}.Dockerfile
8181
platforms: linux/amd64,linux/arm64
8282
push: true
8383
tags: ${{ steps.meta.outputs.tags }}
@@ -127,9 +127,9 @@ jobs:
127127
- name: Setup Node.js
128128
uses: actions/setup-node@v6
129129
with:
130-
node-version: '20'
131-
registry-url: 'https://registry.npmjs.org'
132-
cache: 'npm'
130+
node-version: "20"
131+
registry-url: "https://registry.npmjs.org"
132+
cache: "npm"
133133
cache-dependency-path: ts-sdk/package-lock.json
134134

135135
- name: Install dependencies
@@ -163,15 +163,15 @@ jobs:
163163
run: |
164164
# Get previous tag
165165
PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
166-
166+
167167
if [ -n "$PREV_TAG" ]; then
168168
echo "Generating changelog from $PREV_TAG to HEAD"
169169
CHANGELOG=$(git log $PREV_TAG..HEAD --pretty=format:"- %s (%h)" --no-merges)
170170
else
171171
echo "No previous tag found, using all commits"
172172
CHANGELOG=$(git log --pretty=format:"- %s (%h)" --no-merges -20)
173173
fi
174-
174+
175175
# Write to file for multi-line output
176176
echo "$CHANGELOG" > changelog.txt
177177

‎.github/workflows/security.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,7 @@ jobs:
118118
uses: docker/build-push-action@v6
119119
with:
120120
context: .
121-
file: ./${{ matrix.service }}/Dockerfile
121+
file: ./Docker/${{ matrix.service }}.Dockerfile
122122
push: false
123123
load: true
124124
tags: matchbook-${{ matrix.service }}:scan

‎CHANGELOG.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
### Added
11+
- Comprehensive developer documentation
12+
- OpenAPI 3.0 specification for REST API
13+
- Architecture documentation with diagrams
14+
- Getting started guide for integrators
15+
- API and WebSocket reference documentation
16+
- SDK usage guide for Rust and TypeScript
17+
- FAQ documentation
18+
- Runbooks for operational troubleshooting
19+
- Incident response and maintenance procedures
20+
- Alerting rules with Prometheus Alertmanager
21+
- Monitoring setup with Prometheus and Grafana
22+
- CI/CD pipelines for automated testing and deployment
23+
- Kubernetes manifests for production deployment
24+
- Docker configuration for all services
25+
26+
### Changed
27+
- Updated README with project overview and quick start guide
28+
29+
## [0.1.0] - 2026-01-30
30+
31+
### Added
32+
- Initial release of Matchbook
33+
- On-chain Solana program with order book implementation
34+
- Core instructions: CreateMarket, CreateOpenOrders, Deposit, PlaceOrder, CancelOrder, MatchOrders, ConsumeEvents, Withdraw
35+
- Red-black tree order book data structure
36+
- Event queue for matching events
37+
- Indexer service with Geyser integration
38+
- REST API server with market data endpoints
39+
- WebSocket API for real-time streaming
40+
- Crank service for automated order matching
41+
- Rust SDK for client integration
42+
- TypeScript SDK for web applications
43+
- Docker Compose for local development
44+
45+
### Security
46+
- Non-custodial design with user-controlled funds
47+
- On-chain validation for all operations
48+
- Signed request authentication for trading endpoints
49+
50+
[Unreleased]: https://github.com/joaquinbejar/matchbook/compare/v0.1.0...HEAD
51+
[0.1.0]: https://github.com/joaquinbejar/matchbook/releases/tag/v0.1.0

‎CONTRIBUTING.md‎

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
# Contributing to Matchbook
2+
3+
Thank you for your interest in contributing to Matchbook! This document provides guidelines and instructions for contributing.
4+
5+
## Code of Conduct
6+
7+
By participating in this project, you agree to maintain a respectful and inclusive environment for everyone.
8+
9+
## Getting Started
10+
11+
### Prerequisites
12+
13+
- Rust 1.75+
14+
- Solana CLI 1.18+
15+
- Node.js 18+ (for TypeScript SDK)
16+
- Docker (for local development)
17+
18+
### Setup
19+
20+
1. Fork the repository
21+
2. Clone your fork:
22+
```bash
23+
git clone https://github.com/YOUR_USERNAME/matchbook.git
24+
cd matchbook
25+
```
26+
3. Add upstream remote:
27+
```bash
28+
git remote add upstream https://github.com/joaquinbejar/matchbook.git
29+
```
30+
4. Install dependencies:
31+
```bash
32+
# Rust
33+
cargo build
34+
35+
# TypeScript SDK
36+
cd ts-sdk && npm install
37+
```
38+
39+
## Development Workflow
40+
41+
### 1. Create a Branch
42+
43+
```bash
44+
git checkout -b feature/your-feature-name
45+
# or
46+
git checkout -b fix/your-bug-fix
47+
```
48+
49+
### 2. Make Changes
50+
51+
- Follow the coding standards (see below)
52+
- Write tests for new functionality
53+
- Update documentation as needed
54+
55+
### 3. Test Your Changes
56+
57+
```bash
58+
# Run all tests
59+
cargo test --all-features
60+
61+
# Run clippy
62+
cargo clippy --all-targets --all-features -- -D warnings
63+
64+
# Check formatting
65+
cargo fmt --all --check
66+
67+
# TypeScript SDK
68+
cd ts-sdk && npm test
69+
```
70+
71+
### 4. Commit Your Changes
72+
73+
Write clear, concise commit messages:
74+
75+
```bash
76+
git commit -m "feat: add new order type support"
77+
git commit -m "fix: resolve race condition in matching"
78+
git commit -m "docs: update API reference"
79+
```
80+
81+
Follow [Conventional Commits](https://www.conventionalcommits.org/):
82+
83+
| Prefix | Description |
84+
|--------|-------------|
85+
| `feat` | New feature |
86+
| `fix` | Bug fix |
87+
| `docs` | Documentation |
88+
| `refactor` | Code refactoring |
89+
| `test` | Adding tests |
90+
| `chore` | Maintenance |
91+
92+
### 5. Push and Create PR
93+
94+
```bash
95+
git push origin feature/your-feature-name
96+
```
97+
98+
Then create a Pull Request on GitHub.
99+
100+
## Coding Standards
101+
102+
### Rust
103+
104+
Follow the guidelines in `.internalDoc/09-rust-guidelines.md`:
105+
106+
- Use `#[must_use]` on pure functions
107+
- Use checked arithmetic (no `.unwrap()` in production code)
108+
- Write doc comments on all public items
109+
- Keep functions focused and small
110+
- Use meaningful variable names
111+
112+
Example:
113+
114+
```rust
115+
/// Calculates the total value of an order.
116+
///
117+
/// # Arguments
118+
///
119+
/// * `price` - The price per unit in base units
120+
/// * `quantity` - The quantity in base units
121+
///
122+
/// # Returns
123+
///
124+
/// The total value, or `None` if overflow occurs.
125+
#[must_use]
126+
pub fn calculate_total(price: u64, quantity: u64) -> Option<u64> {
127+
price.checked_mul(quantity)
128+
}
129+
```
130+
131+
### TypeScript
132+
133+
- Use TypeScript strict mode
134+
- Document public APIs with TSDoc
135+
- Use meaningful variable names
136+
- Prefer `const` over `let`
137+
138+
Example:
139+
140+
```typescript
141+
/**
142+
* Calculates the total value of an order.
143+
* @param price - The price per unit
144+
* @param quantity - The quantity
145+
* @returns The total value
146+
*/
147+
export function calculateTotal(price: bigint, quantity: bigint): bigint {
148+
return price * quantity;
149+
}
150+
```
151+
152+
## Pull Request Guidelines
153+
154+
### Before Submitting
155+
156+
- [ ] Tests pass locally
157+
- [ ] Code follows style guidelines
158+
- [ ] Documentation is updated
159+
- [ ] Commit messages are clear
160+
- [ ] PR description explains the changes
161+
162+
### PR Description Template
163+
164+
```markdown
165+
## Summary
166+
167+
[Brief description of changes]
168+
169+
## Changes
170+
171+
- [Change 1]
172+
- [Change 2]
173+
174+
## Testing
175+
176+
- [ ] Unit tests added/updated
177+
- [ ] Integration tests added/updated
178+
- [ ] Manual testing performed
179+
180+
## Related Issues
181+
182+
Closes #[issue_number]
183+
```
184+
185+
### Review Process
186+
187+
1. Automated CI checks must pass
188+
2. At least one maintainer review required
189+
3. Address review feedback promptly
190+
4. Squash commits before merge (if requested)
191+
192+
## Testing
193+
194+
### Unit Tests
195+
196+
```rust
197+
#[cfg(test)]
198+
mod tests {
199+
use super::*;
200+
201+
#[test]
202+
fn test_calculate_total() {
203+
assert_eq!(calculate_total(100, 10), Some(1000));
204+
assert_eq!(calculate_total(u64::MAX, 2), None);
205+
}
206+
}
207+
```
208+
209+
### Integration Tests
210+
211+
Place integration tests in `tests/` directory:
212+
213+
```rust
214+
// tests/integration_test.rs
215+
use matchbook_program::*;
216+
217+
#[tokio::test]
218+
async fn test_place_order_flow() {
219+
// Test implementation
220+
}
221+
```
222+
223+
### Property-Based Tests
224+
225+
For critical algorithms, use property-based testing:
226+
227+
```rust
228+
use proptest::prelude::*;
229+
230+
proptest! {
231+
#[test]
232+
fn test_price_conversion_roundtrip(price in 1u64..u64::MAX) {
233+
let converted = to_human(price);
234+
let back = to_native(converted);
235+
prop_assert_eq!(price, back);
236+
}
237+
}
238+
```
239+
240+
## Documentation
241+
242+
### Code Documentation
243+
244+
- Document all public items
245+
- Include examples in doc comments
246+
- Use `# Examples` section for code samples
247+
248+
### User Documentation
249+
250+
- Update relevant docs in `docs/`
251+
- Keep examples up to date
252+
- Use clear, concise language
253+
254+
## Getting Help
255+
256+
- **Questions**: Open a [Discussion](https://github.com/joaquinbejar/matchbook/discussions)
257+
- **Bugs**: Open an [Issue](https://github.com/joaquinbejar/matchbook/issues)
258+
- **Security**: See [SECURITY.md](SECURITY.md)
259+
- **Chat**: Join our [Discord](https://discord.gg/matchbook)
260+
261+
## License
262+
263+
By contributing, you agree that your contributions will be licensed under the MIT License.

‎Cargo.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@ anyhow = "1.0"
6969

7070
# Logging
7171
tracing = "0.1"
72+
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
7273

7374
# Solana types
7475
bs58 = "0.5"

0 commit comments

Comments
 (0)