# siddharth77s/potens-intern-backend-siddharth-shinde architecture

> Architecture diagram of the GitHub repository siddharth77s/potens-intern-backend-siddharth-shinde, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/siddharth77s/potens-intern-backend-siddharth-shinde
- Repository: https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde

## Overview

1. This is a Node.js/Express REST API centered on scholarship matching. The main runtime boundary is the HTTP server in `src/app.js`, which wires middleware and mounts four route groups: recommendations, item CRUD, explanation, and subscriptions.

2. The core business logic is intentionally centralized in `src/lib/eligibility.js`. That module owns the eligibility model, hard-gate checks, ranking/scoring, and human-readable reason generation, so routes stay thin and mostly translate HTTP requests into calls into this single matching engine.

3. The primary data store is a JSON-file datastore behind `src/db.js`. It persists both the scholarship catalogue and subscription records, exposing repository-style operations like list/get/insert/update/remove. This is the main persistence boundary and is what makes the app portable without a real database server.

4. The seeded scholarship catalogue lives in `src/data/catalogue.js`, and `scripts/seed.js` populates the datastore from it. The catalogue is the domain dataset the entire API operates on; all recommendation, explanation, and admin CRUD flows ultimately read or modify this collection.

5. `POST /recommend` is the main public query path. It validates the required profile fields, runs the profile against the catalogue through the eligibility engine, ranks eligible items, truncates to the top 3, and returns an explanation paragraph for each match. This endpoint also includes metadata like total eligible count and total catalogue size.

6. Recommendation results are cached in-memory in `src/lib/cache.js` using a TTL-based cache keyed by a stable serialization of the profile. Any catalogue write through the admin item endpoints flushes the cache, so recommendation freshness is bounded by either 5 minutes or the next item mutation.

7. The admin-controlled catalogue management surface is `GET/POST/PUT/DELETE /items` in `src/routes/items.js`, protected by `src/middleware/adminAuth.js`. The auth boundary is a shared-secret header check (`x-admin-token`) rather than a broader auth system, and writes have side effects beyond persistence: they invalidate recommendation cache and may trigger subscription notifications.

8. `GET /explain/:item_id` is a read-only introspection endpoint. It uses the same eligibility definition as recommendations, but renders it as plain-language bullet rules instead of evaluating a specific profile. This is a separate presentation path over the same domain rules, not a different rule engine.

9. `POST /subscribe` and `DELETE /subscribe/:id` implement the webhook subscription flow in `src/routes/subscribe.js`, with delivery logic in `src/lib/webhook.js`. Subscriptions store a profile plus a callback URL; when a new item is created and that profile qualifies, the API sends a best-effort outbound POST to the subscriber’s webhook. Webhook failure does not block catalogue writes.

10. OpenAPI generation is built into the route layer via JSDoc and `src/lib/openapi.js`, exposing `/docs` and `/openapi.json` for interactive and machine-readable API contracts. This means the route files are not just handlers but also the source of truth for the API specification.

11. Testing is end-to-end oriented with Jest and Supertest in `tests/api.test.js`, using `tests/setup.js` to isolate state in a separate test database file. The test suite exercises the key architectural boundaries: eligibility edge cases, ranking and top-3 capping, admin auth, CRUD lifecycle, explain behavior, cache-adjacent flows, and webhook subscription validation.

12. Overall, the architecture is a thin HTTP layer over a single matching engine and a file-backed repository, with two auxiliary cross-cutting concerns: ephemeral caching for performance and outbound webhooks for notifications. The key diagram boundaries are: HTTP routes, shared eligibility logic, JSON datastore, in-memory cache, and webhook delivery to external subscriber URLs.

Main entry points: [`src/db.js`](https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/db.js) (Datastore), [`src/routes/items.js`](https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/routes/items.js) (Items), [`src/app.js`](https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/app.js) (App), [`src/routes/recommend.js`](https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/routes/recommend.js) (Recommend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["HTTP API"]
  node_app["App<br/>express server<br/>[app.js]"]
  node_route_recommend["Recommend<br/>route<br/>[recommend.js]"]
  node_route_items["Items<br/>admin route<br/>[items.js]"]
  node_route_explain["Explain<br/>route<br/>[explain.js]"]
  node_route_subscribe["Subscribe<br/>route<br/>[subscribe.js]"]
  node_admin_auth["Admin Auth<br/>header guard<br/>[adminAuth.js]"]
end

subgraph group_domain["Matching Logic"]
  node_eligibility{{"Eligibility<br/>matching engine<br/>[eligibility.js]"}}
  node_cache[("Cache<br/>[cache.js]")]
end

subgraph group_data["Persistence"]
  node_db[("Datastore<br/>json repository<br/>[db.js]")]
  node_catalogue["Catalogue<br/>seed data<br/>[catalogue.js]"]
end

subgraph group_integration["Notifications & Docs"]
  node_openapi["OpenAPI<br/>spec generator<br/>[openapi.js]"]
  node_webhook["Webhook<br/>delivery client<br/>[webhook.js]"]
end

subgraph group_tooling["Tooling & Tests"]
  node_seed["Seed Script<br/>bootstrap script<br/>[seed.js]"]
  node_tests["API Tests<br/>integration tests<br/>[api.test.js]"]
  node_setup["Test Setup<br/>test harness<br/>[setup.js]"]
end

node_app -->|"mounts"| node_route_recommend
node_app -->|"mounts"| node_route_items
node_app -->|"mounts"| node_route_explain
node_app -->|"mounts"| node_route_subscribe
node_route_recommend -->|"score"| node_eligibility
node_route_recommend -->|"read"| node_db
node_route_recommend -->|"lookup"| node_cache
node_route_items -->|"protects"| node_admin_auth
node_route_items -->|"crud"| node_db
node_route_items -->|"flush"| node_cache
node_route_items -->|"notify"| node_webhook
node_route_explain -->|"render"| node_eligibility
node_route_explain -->|"read"| node_db
node_route_subscribe -->|"store"| node_db
node_route_subscribe -->|"deliver"| node_webhook
node_webhook -->|"read"| node_db
node_seed -->|"source"| node_catalogue
node_seed -->|"populate"| node_db
node_openapi -->|"documents"| node_route_recommend
node_openapi -->|"documents"| node_route_items
node_openapi -->|"documents"| node_route_explain
node_openapi -->|"documents"| node_route_subscribe
node_tests -->|"exercise"| node_app
node_tests -->|"configure"| node_setup
node_tests -->|"verify"| node_eligibility
node_tests -->|"isolate"| node_db

click node_app "https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/app.js"
click node_route_recommend "https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/routes/recommend.js"
click node_route_items "https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/routes/items.js"
click node_route_explain "https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/routes/explain.js"
click node_route_subscribe "https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/routes/subscribe.js"
click node_admin_auth "https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/middleware/adminAuth.js"
click node_eligibility "https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/lib/eligibility.js"
click node_cache "https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/lib/cache.js"
click node_openapi "https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/lib/openapi.js"
click node_webhook "https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/lib/webhook.js"
click node_db "https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/db.js"
click node_catalogue "https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/data/catalogue.js"
click node_seed "https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/scripts/seed.js"
click node_tests "https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/tests/api.test.js"
click node_setup "https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/tests/setup.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_route_recommend,node_route_items,node_route_explain,node_route_subscribe,node_admin_auth toneBlue
class node_eligibility,node_cache toneAmber
class node_db,node_catalogue toneMint
class node_openapi,node_webhook toneRose
class node_seed,node_tests,node_setup toneIndigo
```

## Components

### HTTP API

Express server, middleware, and route entrypoints.

- [App](https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/app.js): express server · Wires middleware and mounts the API route groups. · `src/app.js`
- [Recommend](https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/routes/recommend.js): route · Handles profile validation, scoring, ranking, and top-3 responses. · `src/routes/recommend.js`
- [Items](https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/routes/items.js): admin route · Admin CRUD surface for catalogue management. · `src/routes/items.js`
- [Explain](https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/routes/explain.js): route · Explains item eligibility as readable rules. · `src/routes/explain.js`
- [Subscribe](https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/routes/subscribe.js): route · Manages webhook subscriptions and delivery-triggered flows. · `src/routes/subscribe.js`
- [Admin Auth](https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/middleware/adminAuth.js): header guard · Shared-secret check for admin item writes. · `src/middleware/adminAuth.js`

### Matching Logic

Eligibility model, ranking, and response shaping.

- [Eligibility](https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/lib/eligibility.js): matching engine · Centralized hard gates, scoring, ranking, and reason generation. · `src/lib/eligibility.js`
- [Cache](https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/lib/cache.js): ttl cache · In-memory recommendation cache keyed by profile serialization. · `src/lib/cache.js`

### Persistence

File-backed datastore and seeded catalogue.

- [Datastore](https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/db.js): json repository · File-backed persistence for catalogue items and subscriptions. · `src/db.js`
- [Catalogue](https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/data/catalogue.js): seed data · Seed scholarship dataset used by recommendations and CRUD. · `src/data/catalogue.js`

### Notifications & Docs

Webhooks and OpenAPI generation.

- [OpenAPI](https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/lib/openapi.js): spec generator · Builds API documentation from route annotations. · `src/lib/openapi.js`
- [Webhook](https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/src/lib/webhook.js): delivery client · Sends best-effort outbound POSTs to subscriber callback URLs. · `src/lib/webhook.js`

### Tooling & Tests

Bootstrap and end-to-end verification.

- [Seed Script](https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/scripts/seed.js): bootstrap script · Populates the datastore from the seeded catalogue. · `scripts/seed.js`
- [API Tests](https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/tests/api.test.js): integration tests · End-to-end Jest/Supertest coverage of the main boundaries. · `tests/api.test.js`
- [Test Setup](https://github.com/siddharth77s/potens-intern-backend-siddharth-shinde/blob/main/tests/setup.js): test harness · Isolates test state and test database configuration. · `tests/setup.js`

## Connections

- App → Recommend: mounts · Registers the recommendation endpoint group.
- App → Items: mounts · Registers the admin item CRUD routes.
- App → Explain: mounts · Registers the item explanation routes.
- App → Subscribe: mounts · Registers subscription routes.
- Recommend → Eligibility: score · Validates profiles and ranks eligible scholarships.
- Recommend → Datastore: read · Loads catalogue records for recommendation queries.
- Recommend → Cache: lookup · Uses cached results for repeated profiles.
- Items → Admin Auth: protects · Requires the admin token for write access.
- Items → Datastore: crud · Lists, inserts, updates, and removes catalogue items.
- Items → Cache: flush · Invalidates cached recommendations after writes.
- Items → Webhook: notify · Triggers subscription delivery on qualifying new items.
- Explain → Eligibility: render · Turns eligibility rules into plain-language explanations.
- Explain → Datastore: read · Looks up the item to explain.
- Subscribe → Datastore: store · Persists and removes subscription records.
- Subscribe → Webhook: deliver · Uses webhook delivery for subscription notifications.
- Webhook → Datastore: read · Reads subscriptions to find matching callbacks.
- Seed Script → Catalogue: source · Bootstraps data from the seeded scholarship catalogue.
- Seed Script → Datastore: populate · Writes the initial dataset into the datastore.
- OpenAPI → Recommend: documents · Consumes route annotations to generate API docs.
- OpenAPI → Items: documents · Consumes route annotations to generate API docs.
- OpenAPI → Explain: documents · Consumes route annotations to generate API docs.
- OpenAPI → Subscribe: documents · Consumes route annotations to generate API docs.
- API Tests → App: exercise · Runs the HTTP API end-to-end through the server boundary.
- API Tests → Test Setup: configure · Uses test harness setup for isolated state.
- API Tests → Eligibility: verify · Checks eligibility, ranking, and explanation edge cases.
- API Tests → Datastore: isolate · Targets a separate test datastore file.
