StellarStream Maintainer Guide

A lightweight playbook for maintainers covering issue triage, label hygiene, release preparation, and local verification. Keep this document up to date as the project evolves.

Who This Guide Is For
Repository At a Glance
Issue Triage
Label System
PR Review Process
Local Verification Steps
Release Process
Contract Readiness
Known Limitations & Watchlist
Conflict Resolution
Deployment & Monitoring
Security & Maintenance
Community Management Guidelines
Maintainer Handoff

Who This Guide Is For

This guide is for anyone with merge access to the StellarStream repository. It assumes you are already familiar with the project's README and can run the app locally. It is not a contributor onboarding guide — direct new contributors to CONTRIBUTING.md and the project README instead.

Repository At a Glance

Layer	Location	Port	Tech
Frontend	`frontend/`	3000	React + Vite + Tailwind
Backend	`backend/`	3001	Node.js + Express + SQLite
Contract	`contracts/`	—	Rust + Soroban
Backlog	`backlog/`	—	Markdown task drafts

Key entry points:

Backend API server: backend/src/index.ts
Stream logic & math: backend/src/services/streamStore.ts
Database schema: backend/src/services/db.ts
React root: frontend/src/App.tsx
Contract: contracts/src/lib.rs

Issue Triage

Triage Cadence

Aim to triage new issues within 48 hours of opening.

A triaged issue has:

A label (type + area)
An assignee or help wanted tag
A brief maintainer comment if clarification is needed

Triage Decision Tree

New issue opened
│
├── Is it a duplicate?
│   └── Yes → Close with link to original. Add label: duplicate
│
├── Is the report unclear / missing reproduction steps?
│   └── Yes → Comment requesting info. Add label: needs-info
│       └── No response in 7 days → Close with note. Label: stale
│
├── Is it a bug?
│   ├── Affects backend API or DB? → Label: bug, backend
│   ├── Affects frontend UI or polling? → Label: bug, frontend
│   ├── Affects contract logic? → Label: bug, contract
│   └── Assign to yourself or a known contributor
│
├── Is it a feature request / enhancement?
│   └── Label: enhancement + relevant area label
│       └── Add to backlog/ if approved but not immediately prioritized
│
└── Is it a maintenance/chore task?
    └── Label: chore, and link to related area

Grooming Backlog Issues

During each release cycle, review open issues with backlog or help wanted labels:

Close any issues that are superseded by merged PRs or architecture changes
Move implementation task drafts from backlog/ folder into real GitHub Issues when they are ready to be worked on
Update milestone assignments

Label System

Recommended Label Set

Label	Color	Purpose
`bug`	#d73a4a	Something isn't working correctly
`enhancement`	#a2eeef	New feature or improvement request
`chore`	#e4e669	Maintenance, config, CI, docs
`frontend`	#0075ca	Scoped to `frontend/`
`backend`	#e99695	Scoped to `backend/`
`contract`	#f9d0c4	Scoped to `contracts/`
`needs-info`	#d876e3	Waiting on reporter to clarify
`duplicate`	#cfd3d7	Already reported elsewhere
`stale`	#cfd3d7	Inactive and pending closure
`good first issue`	#7057ff	Suitable for new contributors
`help wanted`	#008672	Open for community pick-up
`breaking`	#b60205	Introduces a breaking API or schema change
`blocked`	#e11d48	Waiting on another issue or external dependency

Best Practice: Always apply at least one area label (frontend, backend, contract) alongside a type label (bug, enhancement, chore) so issues are filterable by component.

PR Review Process

Review Goals

Every review should answer three questions:

Does the change solve the stated problem?
Does it preserve the project's reliability and security?
Is the implementation clear enough for a future maintainer to understand?

Pre-Review Checklist

Before reviewing a PR, verify:

CI/CD checks are green or the failures are clearly unrelated
The branch has no unresolved merge conflicts with main
The PR description explains the problem, the change, and the testing performed
The PR links to the relevant issue or ticket
The diff is scoped to the stated work and does not include unrelated changes

Objective Review Checklist

Use the following rubric for each review:

Correctness

The change matches the issue requirements and does not introduce regressions
Error handling is explicit and user-facing failures are understandable
Edge cases and failure modes are considered

Testing

New or changed behavior is covered by tests when appropriate
Existing relevant tests still pass
No test was weakened or removed without explanation

Security

No secrets, tokens, or credentials are introduced into code or config
Input validation and authorization checks are present where needed
Sensitive data is not exposed in logs, responses, or error messages

Maintainability

The implementation follows project conventions and existing patterns
Comments explain intent where the logic is non-obvious
No unnecessary dependencies or large refactors are included
Documentation is updated when behavior, API surface, or deployment changes

Reviewer Decision Rules

Approve when the required checks pass and no critical concerns remain.
Request changes when the PR is missing tests, introduces a security risk, or changes behavior without sufficient justification.
Comment only when you have a concrete suggestion; avoid style-only nits unless they materially affect readability or consistency.
For large or risky changes, ask for a short walkthrough or design note before approval.

Review Comment Templates

For Approval:

✅ Looks good. This PR:
- Implements the requested change for [issue #X]
- Includes appropriate validation and tests
- Does not introduce obvious regressions
- Ready to merge.

For Changes Requested:

Thanks for the PR. I have a few blocking concerns:

1. **[File/Function]**: [Specific feedback]
   - Why: [Explanation]
   - Suggested fix: [How to address it]

2. **[File/Function]**: [Specific feedback]

Please address these items and re-request review when ready.

Merge Strategy

Use Squash and merge for small PRs or routine fixes
Use Create a merge commit when preserving multiple logical commits matters
Use Rebase and merge for small, time-sensitive hotfixes when history should stay linear
Delete the branch after merge unless there is a documented reason to keep it open

Local Verification Steps

Run these checks before approving any PR that touches shared infrastructure.

Full Stack Startup

# From repo root
npm run install:all
npm run dev:backend   # Terminal 1 — starts backend on :3001
npm run dev:frontend  # Terminal 2 — starts frontend on :3000

Expected output (backend):

Server running on port 3001
Database initialized
Event indexer started

Expected output (frontend):

VITE ready in Xms
➜  Local: http://localhost:3000/

Backend API Smoke Tests

# Health check
curl http://localhost:3001/api/health

# List streams (empty is fine on fresh DB)
curl http://localhost:3001/api/streams

# Create a test stream
curl -X POST http://localhost:3001/api/streams \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "GABC1234",
    "recipient": "GXYZ5678",
    "assetCode": "USDC",
    "totalAmount": 100,
    "durationSeconds": 120
  }'

# Note the returned stream ID, then fetch it
curl http://localhost:3001/api/streams/<id>

# Fetch event history
curl http://localhost:3001/api/streams/<id>/history

# Cancel the stream
curl -X POST http://localhost:3001/api/streams/<id>/cancel

Stream Math Verification

Given a stream with totalAmount=100, durationSeconds=120, startAt=T:

Time	Expected	Actual
At T (just started)	vested ≈ 0, status = active	✓
At T + 60s (halfway)	vested ≈ 50, remaining ≈ 50	✓
At T + 120s (done)	vested = 100, status = completed	✓
Before T	status = scheduled	✓
After cancel	status = canceled	✓

Verify these values appear correctly in the frontend stream table and via GET /api/streams/:id.

Frontend Checks

Dashboard loads at http://localhost:3000 with no console errors
Stream list auto-refreshes every ~5 seconds (observe network tab)
Creating a stream via the form adds it to the list immediately
Canceling a stream updates its status in the table
Stream timeline (StreamTimeline component) shows created event after creation
Metrics panel (active / completed / vested totals) updates after changes

Database Inspection (Optional)

# SQLite CLI — inspect streams table directly
sqlite3 backend/data/streams.db

sqlite> .tables
sqlite> SELECT id, sender, recipient, status FROM streams ORDER BY createdAt DESC LIMIT 5;
sqlite> SELECT * FROM stream_events ORDER BY timestamp DESC LIMIT 10;
sqlite> .quit

Release Process

StellarStream uses the GitHub workflow in .github/workflows/release.yml to automate versioning, changelog updates, and container image publishing.

Step-by-Step Release Checklist

Confirm release readiness
- Review open PRs and ensure the changelog, docs, and deployment notes are updated.
- Make sure the main branch is green and that the release scope is clear.
Verify the codebase locally
```
npm run install:all
cd backend && npm run test
cd ../frontend && npm run test
cd .. && npm run build
```
- If a change affects deployment or configuration, also review the relevant docs in DEPLOYMENT.md and RUNBOOK.md.
Use conventional commits for merged work
- fix: → patch release
- feat: → minor release
- feat!: or fix!: with a BREAKING CHANGE footer → major release
- If a PR merges without a conventional commit prefix, adjust the title or ask the author to amend it before release.
Wait for the release-please PR
- The workflow opens a release PR automatically after changes land on main.
- Review the generated PR for the version bump, changelog entries, and any unexpected file changes.
Merge the release PR
- Merging it creates the GitHub Release and the version tag.
- The publish job builds and pushes Docker images to GHCR.
Verify the release artifacts
- Confirm the GitHub Release exists and the tag points to the expected commit.
- Confirm the backend and frontend images are published to GHCR.
- Validate the deployed health endpoint and a basic smoke test against the live environment.
Communicate the release
- Share the release summary in the project channels.
- Note any migration steps, breaking changes, or follow-up work in the release notes.

Expected Release Artifacts

GitHub Release and git tag (for example, v1.1.0)
Updated CHANGELOG.md
Docker images tagged with latest and the version tag

Manual Fallback (Only if Needed)

If the automated release workflow fails or does not open a release PR, inspect the recent merge history and confirm the commit messages follow conventional commit rules before creating a release manually. Avoid manual tagging unless the automation is clearly broken.

Post-Release Checklist

Verify GET /api/health responds on the deployed instance
Create a test stream via the frontend and confirm it appears in the list
Cancel the test stream and confirm its status updates correctly
Close the current milestone (if used) and open the next one

Contract Readiness

The Soroban contract in contracts/src/lib.rs is a scaffold — it is not yet wired into the backend runtime in this MVP. Use the following checks when evaluating contract-related PRs or preparing for the integration milestone.

Build Check

cd contracts
cargo build --target wasm32-unknown-unknown --release

A clean build produces a .wasm file in target/wasm32-unknown-unknown/release/. No warnings about unused methods is a good sign.

Supported Contract Methods

Method	Status
`create_stream(...)`	Implemented
`get_stream(stream_id)`	Implemented
`claimable(stream_id, at_time)`	Implemented
`claim(stream_id, recipient, amount)`	Accounting only — token transfer not wired
`cancel(stream_id, sender)`	Implemented

Testnet Deployment

SECRET_KEY="S..." npm run deploy:contract

After deployment:

Copy the contract ID from the output or contracts/contract_id.txt
Set CONTRACT_ID=<id> in backend/.env
Set SERVER_PRIVATE_KEY=<key> in backend/.env
Restart the backend

⚠️ Never commit contracts/contract_id.txt or .env files containing secret keys to version control.

Contract ↔ Backend Interface

When contract methods change, update backend/src/services/streamStore.ts to match. The backend currently uses SQLite as the source of truth; Soroban state is supplementary until full integration is complete.

Known Limitations & Watchlist

Keep these on your radar when reviewing PRs or triaging issues. They are not bugs — they are known gaps in the current MVP.

Area	Limitation	Risk if Unaddressed
Contract	Not connected to backend runtime	On-chain state diverges from SQLite
Auth	No authentication on write endpoints (`POST /api/streams`, `POST /api/streams/:id/cancel`)	Any caller can create or cancel streams
Wallet	No wallet sign/transaction flow in UI	Users cannot sign transactions
Token Transfer	`claim` updates accounting only — no actual token movement	Misleading balance displays
Event Indexer	Polls every 10 seconds — configurable but hardcoded	May miss rapid contract events
Test Coverage	Minimal — CI can be expanded	Regressions may go undetected

When a PR claims to fix one of these, verify end-to-end, not just the unit level.

Conflict Resolution

Merge Conflict Prevention

Enforce the Git Workflow Guide (see GIT_WORKFLOW_GUIDE.md)
Require branch updates before PR merge
Communicate about shared files (package.json, routes)
Keep PRs small and focused

Handling Conflicts

If conflicts occur during review:

Comment on PR: "Please rebase with latest main to resolve conflicts"

Provide command:

git fetch origin
git rebase origin/main
git push --force-with-lease

If conflicts are complex:

Schedule a sync with the contributor
Pair program to resolve
Document the resolution for future reference

Package.json Conflicts:

Manually merge dependency versions
Run npm install to verify
Test that both features still work
Commit the resolved package-lock.json

Deployment & Monitoring

Pre-Deployment Checklist

Deployment Steps

Build Docker images (if applicable)
```
docker build -t stellar-stream:v0.x.x .
```
Deploy to staging first
- Verify all features work
- Check logs for errors
- Run smoke tests
Deploy to production
- Use blue-green deployment if possible
- Monitor error rates and performance
- Have rollback plan ready

Monitoring & Alerts

Monitor error logs for exceptions
Track API response times
Alert on failed deployments
Monitor Stellar Testnet connectivity
Track stream creation/cancellation success rates

Rollback Procedure

If critical issues occur post-deployment:

# Revert to previous version
git revert <commit-hash>
git push origin main

# Or redeploy previous tag
docker pull stellar-stream:v0.x.(x-1)
docker run ... stellar-stream:v0.x.(x-1)

Security & Maintenance

Dependency Management

Monthly Security Audit:

npm audit
npm audit fix  # Auto-fix if safe
npm update     # Update to latest compatible versions

Quarterly Major Updates:

Review breaking changes
Test thoroughly
Update documentation
Create a PR for review

Handling Security Disclosures

Do not open a public issue for a security vulnerability. Report it privately through the GitHub Security Advisory form linked in SECURITY.md.
Acknowledge the report within 48 hours and confirm whether the report is valid within 7 days.
Keep the discussion private until a fix is ready. If the issue is urgent, rotate exposed credentials and disable the affected path or deployment while mitigation is prepared.
Coordinate disclosure timing with the reporter, then publish a concise advisory and release note once the fix is available.
If a fix affects a supported release line, backport it to the relevant branch and note the affected versions clearly.

Code Security Review

Check for SQL injection or unsafe query handling in the backend data layer
Verify no hardcoded secrets or tokens are introduced into code or config
Validate user inputs, especially stream amounts, durations, and asset identifiers
Review frontend rendering paths for XSS or unsafe DOM usage
Confirm authentication and authorization are enforced on endpoints that modify state

Dependency Vulnerabilities

Run npm audit regularly and review findings in the context of the current release
Update critical dependencies immediately when a fix is available
Document why non-critical updates are deferred when they are not yet safe to adopt

Community Management Guidelines

The project benefits from a welcoming, constructive, and solution-oriented community. Maintainers should model that tone in every interaction.

Community Expectations

Keep issues, PRs, and discussions focused on the project and the underlying problem
Encourage reproducible bug reports with steps to reproduce, expected behavior, and observed behavior
Thank contributors for their effort, even when the change needs follow-up
Avoid taking disagreements personally or escalating them in public when a private conversation would be more productive

Response Guidelines

Bug reports: Ask for reproduction steps, relevant environment details, and whether the issue is still reproducible
Feature requests: Clarify the use case and link to existing roadmap or related issues when possible
Support questions: Point the user to the docs first, then redirect to GitHub Discussions when appropriate
Negative or hostile behavior: Remind the user of the code of conduct and, if needed, mute or hide disruptive comments

When to Escalate

Escalate to a senior maintainer or the repository owner when:

A contributor is repeatedly disrespectful or disruptive
A report appears to involve a serious security issue
The discussion is blocked by a fundamental disagreement about the project direction

Announcement Template

For major changes or releases:

## 📢 Announcement: [Title]

**What's changing**: [Brief description]

**Why**: [Motivation]

**Timeline**: [When it happens]

**Action needed**: [What users should do]

**Questions?** Comment below or open a Discussion.

Contributor Recognition

Thank contributors in release notes and PRs
Highlight major contributions in README or release notes when appropriate
Invite active contributors to become maintainers when they have demonstrated reliable judgment and contribution quality

Maintainer Handoff

When handing off maintainer responsibilities:

Access — Transfer or add the new maintainer as a repository collaborator with Write or Maintain access.

Secrets — Share any deployment keys, testnet account credentials, or environment secrets through a secure channel (not GitHub issues or PR comments).

Open issues — Walk through the open issue list together and transfer assignees where needed.

Pending PRs — Ensure no PR is left in an ambiguous state (re-request review or close with a note).

This document — Update the "Who This Guide Is For" section and commit the change in the handoff PR.

Useful Commands

# View recent commits
git log --oneline -10

# Check branch status
git branch -vv

# Find who changed a line
git blame <file>

# View PR diff
git diff main..feature-branch

# Squash commits before merge
git rebase -i HEAD~3

# Stash work in progress
git stash
git stash pop

# Cherry-pick a commit
git cherry-pick <commit-hash>

Escalation & Help

Stuck on a decision?

Create a GitHub Discussion
Tag relevant maintainers
Wait for consensus

Contributor being difficult?

Stay professional and kind
Reference CODE_OF_CONDUCT.md
Escalate to senior maintainers if needed

Burnout?

It's okay to step back
Communicate with team
Share responsibilities
Take breaks

Resources

README — Project overview and setup
PR_DESCRIPTION — Example PR workflow and testing
STREAM_EVENTS_IMPLEMENTATION — Event history implementation details

Last Updated: July 2026 Maintained By: StellarStream Core Team

FilesExpand file tree

MAINTAINER_GUIDE.md

Latest commit

History