npm package: @nospt/backstage-plugin-tech-radar-ng-backend
Description: Backstage backend plugin for the NOS Technology Radar
Author: NOS SGPS, S.A.
Latest version: 0.9.7

<div align="center">

<img src="https://raw.githubusercontent.com/nosportugal/backstage-plugin-tech-radar-ng/main/images/logo-backend.png" alt="Tech Radar NG — Backend" width="50%" />

# @nospt/backstage-plugin-tech-radar-ng-backend

**Backend plugin for the Tech Radar NG suite.**

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](../../LICENSE) [![Backstage](https://img.shields.io/badge/Backstage-New%20Backend%20System-blueviolet)](https://backstage.io) [![Beta](https://img.shields.io/badge/status-beta-orange)](#)

</div>

> [!WARNING] > **BETA** — This plugin is under active development. APIs, data models, and configuration options may change between versions.

---

## Overview

This package provides the **backend** for the Tech Radar NG Backstage plugin suite. It includes:

- **Scheduled Discovery** — Automatically discovers technologies from GitHub on a configurable schedule using a 50/50 strategy (top scorers + trending).
- **Temporal Metrics** — Stores timestamped snapshots of stars and forks with percentage-change trend indicators.
- **REST API** — Exposes endpoints for segments, rings, candidates (with pagination/filtering), batch classification, and manual discovery triggers.
- **Database Migrations** — Automatic Knex migrations on startup (PostgreSQL or SQLite).
- **DI Services** — `RadarMetricsService`, `RingsService`, `SegmentsService` following the Backstage service-ref pattern.

Built with the [New Backend System](https://backstage.io/docs/backend-system/) using `createBackendPlugin` and core DI services.

---

## Installation

From your Backstage root:

```bash
yarn --cwd packages/backend add @nospt/backstage-plugin-tech-radar-ng-backend
```

Register the plugin:

```ts
// packages/backend/src/index.ts
const backend = createBackend();
backend.add(import('@nospt/backstage-plugin-tech-radar-ng-backend'));
backend.start();
```

Database migrations run automatically on startup.

---

## Configuration

Add to your `app-config.yaml`:

```yaml
techRadarNg:
  discovery:
    frequency: { hours: 2 } # How often to run discovery (default: 24h)
    timeout: { minutes: 15 } # Max discovery run duration
    initialDelay: { seconds: 5 } # Delay before first run (default: 60s)
  github:
    searchQueries:
      - 'AI OR ML OR "machine learning" OR "artificial intelligence"'
      - 'LLM OR "language model" OR GPT OR transformer'
```

See the full [configuration reference](../../docs/README.md#configuration-reference) for all options.

---

## REST API

All endpoints are served under `/api/tech-radar-ng`.

| Method | Path                   | Description                             |
| ------ | ---------------------- | --------------------------------------- |
| `GET`  | `/segments`            | List all radar segments                 |
| `GET`  | `/rings`               | List all radar rings                    |
| `PUT`  | `/rings`               | Update ring definitions                 |
| `GET`  | `/candidates`          | List candidates (paginated, filterable) |
| `PUT`  | `/candidates/classify` | Batch-update candidate classifications  |
| `GET`  | `/githubDiscovery`     | Manually trigger a discovery run        |

For detailed request/response schemas, see the [API reference](../../docs/README.md#rest-api-reference).

---

## Services

| Service               | Ref                      | Description                                         |
| --------------------- | ------------------------ | --------------------------------------------------- |
| `RadarMetricsService` | `radarMetricsServiceRef` | Discovery engine, candidate CRUD, metrics snapshots |
| `RingsService`        | `ringsServiceRef`        | Ring management                                     |
| `SegmentsService`     | `segmentsServiceRef`     | Segment management                                  |

All services follow the Backstage DI pattern: interface → private constructor with `static create()` factory → `createServiceRef` / `createServiceFactory`.

---

## Development

```bash
cd plugins/tech-radar-ng-backend
yarn start       # Start backend in development mode
yarn test        # Run tests
yarn lint        # Lint
yarn build       # Build for production
```

---

## Related Packages

| Package                                                                   | Description                                       |
| ------------------------------------------------------------------------- | ------------------------------------------------- |
| [`@nospt/backstage-plugin-tech-radar-ng`](../tech-radar-ng)               | Frontend — Radar visualization and Back Office UI |
| [`@nospt/backstage-plugin-tech-radar-ng-common`](../tech-radar-ng-common) | Shared types, Zod schemas, and enums              |

---

## License

[Apache License 2.0](../../LICENSE)