<<<<<<< HEAD

StellarOps Indexer

Backend API for indexing GitHub contributor workflow data for Stellar and Soroban open-source projects.

StellarOps Indexer helps maintainers inspect repositories, issues, pull requests, labels, contributors, and issue readiness from a clean API surface. The MVP runs in mock mode by default, so contributors can install and test the project without GitHub tokens.

Why This Exists

Stellar and Soroban maintainers often need better visibility into contributor workflows: open issues, label quality, assigned contributors, pull request status, merged work, repository health, and readiness for new contributors.

StellarOps Indexer is the backend piece of the StellarOps Labs ecosystem:

StellarOps Kit helps maintainers create better contributor issues.
StellarOps Board helps maintainers review issue readiness and repository health.
StellarOps Indexer provides the backend structure for indexing workflow data.

This project is independent and does not claim official affiliation with Stellar, Soroban, Drips Wave, or GrantFox.

Features

Express API server with mock data
Repository, issue, pull request, label, and contributor endpoints
Mock GitHub adapter with Stellar/Soroban-themed data
In-memory storage layer behind an interface
Issue readiness mapper with score, level, missing fields, and suggestions
Vitest and Supertest coverage
GitHub Actions CI
Contributor-ready issue templates and documentation

Tech Stack

Node.js, TypeScript, Express, CORS, dotenv, Vitest, Supertest, ESLint, and GitHub Actions.

Quick Start

npm install
cp .env.example .env
npm run dev

The API starts on http://localhost:4000 by default.

Environment Variables

Variable	Default	Description
`PORT`	`4000`	Local API port
`STELLAROPS_INDEXER_MOCK_MODE`	`true`	Keeps local development token-free
`GITHUB_OWNER`	`stellarops-labs`	Future GitHub adapter owner
`GITHUB_REPOSITORY`	`stellarops-kit`	Future GitHub adapter repository
`GITHUB_TOKEN`	empty	Reserved for future authenticated GitHub API calls

API Endpoints

GET /health
GET /repositories
GET /issues
GET /issues/:id
GET /pull-requests
GET /labels
GET /contributors
POST /index/mock

Mock Mode

Mock mode is enabled by default and does not require secrets. POST /index/mock refreshes data from the mock GitHub adapter into the memory store. Real GitHub API indexing is intentionally isolated behind the adapter interface as a future extension.

Development Commands

npm run dev
npm run lint
npm run typecheck
npm run test
npm run build
npm start

Project Structure

src/api          Express route modules
src/config       Environment loading
src/indexer      Adapter, service, and readiness mapping
src/server       Express app and server entrypoint
src/storage      Memory store and store interface
src/types        Core data models
src/utils        Shared helpers
tests            API, indexer, and storage tests
docs             Architecture and contributor documentation

Roadmap

Phase 1: MVP API, mock adapter, memory store, readiness mapper, docs, tests, and CI
Phase 2: GitHub API adapter, repository import, filtering, persistence, pagination, and rate limit handling
Phase 3: PostgreSQL, Docker, deployment docs, organization analytics, board integration, and webhooks

Contributing

See CONTRIBUTING.md. Good tasks should include the problem, expected behavior, files to update, acceptance criteria, difficulty, and Stellar/Soroban relevance.

License

MIT

stellarops-indexer

API for indexing GitHub issues, pull requests, labels, and contributor activity for Stellar/Soroban open-source projects.

82c9c94563cc47b88b84246a5f0384fcbd9441fd

Lakes41/stellarops-indexer

README