CodePulse

Engineering teams accumulate technical debt faster than they can see it. Senior developers spend review time catching style violations and known anti-patterns instead of evaluating logic and architecture, while genuine debt - high cyclomatic complexity, duplicated blocks, security vulnerabilities - stays invisible until it causes a failure.

Existing tooling does not close this gap well. Enterprise platforms such as SonarQube are resource-heavy, costly, and configured for DevOps specialists, placing them out of reach for small teams and student projects. Lightweight linters run in isolation, forcing developers to move between GitHub, standalone analysis tools, and project boards to assemble a picture of their codebase. Critically, almost all of these tools report only a present-day snapshot: they cannot answer whether code quality is trending upward or downward across sprints, which is the question that actually drives engineering decisions.

CodePulse connects to a GitHub account through OAuth and listens for Pull Request events via webhooks. The API service verifies each event and enqueues an analysis job on a Redis-backed BullMQ queue, responding immediately so the webhook never blocks. A separate worker service consumes the job, clones the repository, detects the languages present, and runs the matching analysis tools - ESLint and typescript-eslint for JavaScript/TypeScript, PyLint, Bandit and Radon for Python, Checkstyle and PMD for Java, Cppcheck for C/C++, and jscpd for cross-language duplication.

Raw findings are normalised into a common schema, then converted into a Health Score and a Debt Score by a deterministic, severity-weighted algorithm — security issues carry more weight than style issues. Determinism is a deliberate design choice: identical input must always yield an identical score, otherwise historical trend comparison is meaningless. Results are written to PostgreSQL, posted to the Pull Request as a categorised bot comment, and evaluated against user-configured quality gates. The React dashboard renders score trends, debt breakdown by category, and worst-offending files, while the mobile app pushes alerts when a gate fails or a high-severity issue is introduced.

Architecture

CodePulse is a TypeScript monorepo containing four deployable units and a shared data layer. The API service (Express) handles GitHub OAuth, JWT session management, webhook ingestion, and all REST endpoints consumed by the two clients. The worker service (BullMQ consumer) performs repository cloning and static analysis in an isolated process. The two communicate exclusively through a Redis job queue and a shared PostgreSQL database accessed via Prisma, which generates types directly from the schema and gives compile-time safety across every service.

The API/worker split is the central architectural decision. Static analysis of a real repository can take minutes; performing it inline would cause webhook timeouts and make the API unresponsive under load. By decoupling the two, the webhook endpoint always acknowledges within seconds, worker crashes remain non-fatal to the user-facing API, and analysis throughput scales by adding worker replicas rather than rewriting code. Kubernetes was evaluated and rejected — two services do not justify orchestration overhead.

Multi-tenancy is enforced at the organisation level. An Organization entity mirrors a GitHub account owner and acts as the single tenant anchor; membership is synced from GitHub and verified from the database on every request rather than embedded in the JWT, so permission changes take effect immediately. Requests for resources outside a caller's tenant return 404 rather than 403, preventing information leakage about which repositories exist.

Engineering practices

The project follows a feature-slice delivery model rather than layer-based ownership, so each team member gains hands-on experience across the API, database, web, and mobile layers. Work is decomposed into twelve feature slices tracked against a work breakdown structure. Local infrastructure runs through Docker Compose; GitHub Actions enforces linting, type-checking, and builds on every push. Structured JSON logging (Pino), health check endpoints, and Bull Board queue monitoring provide observability across both services.

Reliability and graceful degradation

Jobs are persisted in Redis and retried with exponential backoff, so no analysis is lost to a worker restart. If a single analysis tool fails — for example, PyLint encountering a malformed file — the system completes with the remaining tools and produces a partial score rather than failing the run outright.

Challenges

The most significant challenge was designing a scoring model that is both meaningful and reproducible. Normalising findings from eight independent tools, each with its own severity taxonomy, into a single comparable scale required an explicit mapping layer and a documented weighting rationale. Supporting multiple languages in one worker also demanded a container image carrying Node.js, Python, and Java runtimes concurrently, with each tool wrapped behind a standard adapter interface so new languages can be added without touching existing code.

Future work

A scoped AI insights layer is planned as a downstream feature that summarises findings in natural language for non-technical stakeholders. It is deliberately excluded from the scoring pipeline to preserve determinism. Further directions include GitLab support through the existing provider-adapter abstraction, and semantic duplicate detection using vector embeddings.