Repq1

Repository intelligence for engineering teams

Analyze GitHub repositories for README quality, structure, technical debt, and delivery readiness.
Get actionable scorecards and findings that help teams ship with confidence.

Product Overview

Repq1 helps engineering leads, platform teams, and open source maintainers understand repository health at a glance. It produces deterministic, rule-based scores and findings across multiple dimensions.

What it does:

Analyzes README completeness, clarity, and section coverage
Evaluates repository structure (src, tests, docs, config, CI)
Surfaces technical debt signals from file layout and tooling
Produces actionable findings with severity and recommendations
Supports GitHub App integration for automated sync and webhooks

Why it exists: Manual repo audits don't scale. Repq1 turns repository health into a measurable, improvable metric.

Core Features

Feature	Status	Description
README analysis	Implemented	Section coverage, clarity, onboarding, contribution guidance
Structure analysis	Implemented	src/tests/docs, config hygiene, test presence, technical debt
Health scorecards	Implemented	Overall 0–100 + dimension scores (incl. issue/PR proxy)
GitHub integration	Implemented	App install, webhooks, repo sync
Queue-based analysis	Implemented	BullMQ jobs for sync, analyze, report
Dashboard & reports	Implemented	Next.js UI, score breakdown, findings panel
Report exports	Implemented	JSON, Markdown (PDF planned)
Workspace / team support	Implemented	Workspaces, members, roles (OWNER, ADMIN, MEMBER, VIEWER)

Architecture Overview

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Web       │────▶│  API        │────▶│   Worker    │
│  (Next.js)  │     │  (NestJS)   │     │  (BullMQ)   │
└─────────────┘     └──────┬──────┘     └──────┬──────┘
                           │                    │
                    ┌──────┴──────┐     ┌──────┴──────┐
                    │  PostgreSQL │     │   Redis     │
                    └─────────────┘     └──────┬──────┘
                                               │
                                               ▼
                                        ┌─────────────┐
                                        │  Analyzer   │
                                        │ (FastAPI)   │
                                        └─────────────┘

Component	Stack	Role
web	Next.js 14, React 18, Tailwind	Frontend, dashboard, landing
api	NestJS, Prisma	REST API, orchestration, persistence
worker	TypeScript, BullMQ	Background jobs (sync, analyze, report)
analyzer	Python FastAPI	README and structure scoring
postgres	PostgreSQL 16	Primary data store
redis	Redis 7	BullMQ queue

Repository Structure

repo-analysis-q1/
├── apps/
│   ├── web/          # Next.js frontend
│   ├── api/          # NestJS API
│   ├── worker/       # BullMQ worker
│   └── analyzer/     # Python FastAPI analyzer
├── packages/
│   ├── shared/       # Types, score contracts, logger
│   └── config/       # ESLint, TypeScript, Prettier
├── docs/             # Documentation
├── .github/          # CI, issue templates, PR template
├── docker-compose.yml
├── Makefile
└── package.json

Tech Stack

Layer	Technologies
Frontend	Next.js 14, React 18, Tailwind CSS
API	NestJS, Prisma, class-validator
Worker	BullMQ, Octokit
Analyzer	Python 3.11, FastAPI, Pydantic, Ruff
Data	PostgreSQL, Redis
Infra	Docker, Docker Compose
Monorepo	pnpm workspaces

Local Development

Prerequisites

Node.js 20+
pnpm 9+
Docker and Docker Compose (PostgreSQL, Redis)
Python 3.11+ (analyzer)
uv (recommended for Python) or pip

Step-by-Step Setup

1. Clone the repository

git clone https://github.com/okwn/repo-analysis-q1.git
cd repo-analysis-q1

2. Install dependencies

pnpm install

For the Python analyzer (if using uv):

cd apps/analyzer && uv sync && cd ../..

3. Create environment files

Copy .env.example to .env in each app:

cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env
cp apps/worker/.env.example apps/worker/.env
cp apps/analyzer/.env.example apps/analyzer/.env

4. Start PostgreSQL and Redis

make docker-up
# or: docker compose up -d postgres redis

5. Run database migrations

pnpm db:migrate

6. Seed the database (optional, for demo data)

pnpm db:seed

7. Start all services

pnpm dev

This runs web, api, worker, and analyzer in parallel.

8. Run services individually (alternative)

# Terminal 1 – Web
pnpm dev:web

# Terminal 2 – API
pnpm dev:api

# Terminal 3 – Worker
pnpm dev:worker

# Terminal 4 – Analyzer
make dev-analyzer

9. Access the application

Service	URL
Web UI	http://localhost:3000
Dashboard	http://localhost:3000/dashboard
Dev login	http://localhost:3000/auth/dev
API	http://localhost:3001
API health	http://localhost:3001/health
Analyzer	http://localhost:8000
Analyzer docs	http://localhost:8000/docs

10. Trigger analysis (after seed)

From the web UI: go to a repository → click "Run analysis".
Or from the CLI:

DATABASE_URL=postgresql://repq1:repq1_dev@localhost:5432/repq1 \
REDIS_HOST=localhost REDIS_PORT=6379 \
pnpm db:trigger-analysis

Environment Variables

Database

Variable	Required	Default	Description
`DATABASE_URL`	Yes (api, worker)	`postgresql://repq1:repq1_dev@localhost:5432/repq1`	PostgreSQL connection string

Redis

Variable	Required	Default	Description
`REDIS_HOST`	Yes	`localhost`	Redis host
`REDIS_PORT`	No	`6379`	Redis port
`REDIS_URL`	No	`redis://localhost:6379`	Full Redis URL

GitHub App

Variable	Required	Description
`GITHUB_APP_ID`	For GitHub integration	GitHub App ID
`GITHUB_APP_PRIVATE_KEY`	For GitHub integration	PEM-encoded private key (escape `\n`)
`GITHUB_WEBHOOK_SECRET`	For webhooks	Webhook secret for signature validation
`GITHUB_APP_CLIENT_ID`	Optional	OAuth client ID
`GITHUB_APP_CLIENT_SECRET`	Optional	OAuth client secret

Analyzer

Variable	Required	Default	Description
`ANALYZER_URL`	Yes (api, worker)	`http://localhost:8000`	Analyzer service URL

Web

Variable	Required	Default	Description
`NEXT_PUBLIC_API_URL`	Yes	`http://localhost:3001`	API base URL (used for server-side proxy)

Auth

Variable	Required	Default	Description
`JWT_SECRET`	Production	—	Secret for JWT signing (required in prod unless dev login)
`JWT_EXPIRES_IN`	No	`7d`	JWT expiration (e.g. `7d`, `24h`)
`DEV_ALLOW_DEV_USER`	No	—	Set to `true` to enable `/auth/dev` login
`DEV_USER_ID`	No	—	Default user ID for dev login
`INTERNAL_API_KEY`	Production	—	API key for worker→API calls (exports/process)
`ANALYZER_API_KEY`	Optional	—	API key to protect analyzer (api + worker send it)

Other

Variable	Required	Default	Description
`PORT`	No	`3001`	API port
`NODE_ENV`	No	`development`	`development` \| `production` \| `test`
`CORS_ORIGIN`	Production	—	Comma-separated allowed origins

How the Analysis Flow Works

Repository connected — Via GitHub App install or manual add; webhook or API creates Repository record.
Metadata synced — Worker repo.sync job fetches repo metadata from GitHub API.
Job queued — User or scheduler triggers analysis → repo.analyze job enqueued to Redis.
Analyzer runs — Worker fetches README + file tree from GitHub, calls analyzer /analyze/readme and /analyze/structure.
Score calculated — @repq1/shared aggregateScores() combines readme and structure results.
Findings stored — Findings (readme + structure) saved to Finding table with severity and category.
Report shown in UI — Dashboard and repo detail pages display scorecard and findings.

Docker Usage

Run the full stack in containers:

docker compose up -d --build

Services:

Service	Port	Description
postgres	5432	PostgreSQL
redis	6379	Redis
api	3001	NestJS API
worker	—	BullMQ worker
analyzer	8000	Python analyzer
web	3000	Next.js frontend

Migrations: Run automatically on API startup.

Seed (first run):

docker compose exec api sh -c "cd apps/api && npx prisma db seed"

Trigger analysis (from host):

DATABASE_URL=postgresql://repq1:repq1_dev@localhost:5432/repq1 \
REDIS_HOST=localhost REDIS_PORT=6379 \
pnpm db:trigger-analysis

See docs/docker-local-stack.md for full details.

API / Endpoints Overview

Base URL: http://localhost:3001

Method	Endpoint	Description
GET	`/health`	API health check
GET	`/health/deps`	Dependency health (analyzer)
GET	`/repositories`	List repositories
GET	`/repositories/:id`	Get repository
GET	`/analysis/runs/:repositoryId`	List analysis runs
POST	`/analysis/trigger/:repositoryId`	Trigger analysis
GET	`/analysis/score/:owner/:repo`	Get score (readme + structure + aggregate)
GET	`/github/status`	GitHub integration status

Analyzer (http://localhost:8000):

Method	Endpoint	Description
GET	`/health`	Health check
POST	`/analyze/readme`	Analyze README content
POST	`/analyze/structure`	Analyze repo structure
POST	`/analyze/score`	(Deprecated) Use readme + structure instead

Full reference: docs/endpoints.md

Security Notes

Secrets: Store GITHUB_APP_PRIVATE_KEY, GITHUB_WEBHOOK_SECRET, JWT_SECRET, INTERNAL_API_KEY, ANALYZER_API_KEY, and DATABASE_URL securely. Use a secrets manager in production.
Webhook validation: GitHub webhooks are validated via X-Hub-Signature-256; ensure GITHUB_WEBHOOK_SECRET is set.
Auth: Production uses JWT (JWT_SECRET). Dev mode: set DEV_ALLOW_DEV_USER=true for /auth/dev login.
CORS: CORS_ORIGIN is required in production (comma-separated allowed origins).
Internal API: INTERNAL_API_KEY protects worker-to-API calls (POST /exports/:id/process); required in production.
Analyzer: Set ANALYZER_API_KEY to protect the analyzer service; rate limiting (60/min) applied.
Recommendation: Rotate secrets regularly; use managed PostgreSQL and Redis in production.

Roadmap

Phase	Focus
Current	Core analysis, dashboard, exports (JSON/Markdown), GitHub App, JWT auth, guards
Next	Score trend charts, PDF export, full Issue/PR health (GitHub API)
Later	Custom scoring weights, comparative scoring, AI-assisted analysis

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for guidelines.

Issues: https://github.com/okwn/repo-analysis-q1/issues
Pull requests: https://github.com/okwn/repo-analysis-q1/pulls

License

MIT — see LICENSE for details.

Repq1 — Repository intelligence for engineering teams.
https://github.com/okwn/repo-analysis-q1

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.github		.github
apps		apps
docs		docs
packages		packages
.env.example		.env.example
.gitignore		.gitignore
.npmrc		.npmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
RELEASE_CHECKLIST.md		RELEASE_CHECKLIST.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
rapor1.md		rapor1.md
rapor2.md		rapor2.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Repq1

Product Overview

Core Features

Architecture Overview

Repository Structure

Tech Stack

Local Development

Prerequisites

Step-by-Step Setup

Environment Variables

Database

Redis

GitHub App

Analyzer

Web

Auth

Other

How the Analysis Flow Works

Docker Usage

API / Endpoints Overview

Security Notes

Roadmap

Contributing

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Repq1

Product Overview

Core Features

Architecture Overview

Repository Structure

Tech Stack

Local Development

Prerequisites

Step-by-Step Setup

Environment Variables

Database

Redis

GitHub App

Analyzer

Web

Auth

Other

How the Analysis Flow Works

Docker Usage

API / Endpoints Overview

Security Notes

Roadmap

Contributing

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages