How siddharth77s/potens-intern-backend-siddharth-shinde works
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: db.js Datastore · items.js Items · app.js App · recommend.js Recommend
Components 15
HTTP API
Express server, middleware, and route entrypoints.
- App · Wires middleware and mounts the API route groups.
src/app.js - Recommend · Handles profile validation, scoring, ranking, and top-3 responses.
src/routes/recommend.js - Items · Admin CRUD surface for catalogue management.
src/routes/items.js - Explain · Explains item eligibility as readable rules.
src/routes/explain.js - Subscribe · Manages webhook subscriptions and delivery-triggered flows.
src/routes/subscribe.js - Admin Auth · Shared-secret check for admin item writes.
src/middleware/adminAuth.js
Matching Logic
Eligibility model, ranking, and response shaping.
- Eligibility · Centralized hard gates, scoring, ranking, and reason generation.
src/lib/eligibility.js - Cache · In-memory recommendation cache keyed by profile serialization.
src/lib/cache.js
Persistence
File-backed datastore and seeded catalogue.
Notifications & Docs
Webhooks and OpenAPI generation.
Tooling & Tests
Bootstrap and end-to-end verification.
- Seed Script · Populates the datastore from the seeded catalogue.
scripts/seed.js - API Tests · End-to-end Jest/Supertest coverage of the main boundaries.
tests/api.test.js - Test Setup · Isolates test state and test database configuration.
tests/setup.js
Connections 26
- 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.