05 — Someli-admin-api: where to look
A symptom → location routing table.
Server won't boot
| Symptom |
First place to look |
Cannot find module ... |
yarn install; Node 20 |
Something Went Wrong! |
MySQL unreachable |
EADDRINUSE :::5002 |
Port collision — set port=5004 in .env |
Auth issues
| Symptom |
First place to look |
401 on /auth/* request |
middlewares/auth.js — encrypted-Bearer flow; check TOKEN_HEADER_KEY |
401 on a routes/routes.js endpoint |
methods.ensureToken — plain JWT; check the Authorization: Bearer <token> header |
| Token decryption error |
helper/tokenGenerator.js — check JWT secret and AES key alignment with someli-api |
| Session persistence weird |
express-session secret is hardcoded — restart-tolerant across one process but not across deploys |
| Reference |
../../audit/Someli-admin-api/authentication.md |
A specific endpoint is broken
| Where to look |
When |
routes/auth.js |
The path starts with /auth/ |
routes/routes.js |
Root-mounted endpoints |
helper/<file>.js |
The handler imports it |
actions/actions.js |
The handler uses generic CRUD |
| Endpoint inventory |
../../audit/Someli-admin-api/API-inventory.md |
| Symptom |
First place to look |
| Bad input crashes the handler |
middlewares/validation.js — add an express-validator chain |
Empty req.body |
Confirm the Content-Type header on the request is application/json |
AI / LLM issues
| Symptom |
First place to look |
| Bedrock failures |
helper/aiLogics.js; AWS_BEDROCK_* env vars; the model name must match what's enabled in your AWS region |
| OpenAI failures |
OPENAI_API_KEY |
| Leonardo / Chaskiq / GoogleAPI issues |
Each has its own env var; trace in routes/routes.js |
Paddle / Stripe billing
| Symptom |
First place to look |
| Paddle endpoints exist but webhook handler missing |
server.js exempts the path from JSON parsing, but there's no handler in routes/routes.js. Either vestigial or planned. Verify with the team before adding one. |
| Sandbox vs prod confusion |
PADDLE_ENV and PADDLE_TEST_ENV env vars |
| Reference |
../../audit/Someli-admin-api/API-inventory.md |
Cross-repo / helper-drift issues
| Symptom |
First place to look |
A helper change in someli-api broke admin |
The helpers tokenGenerator.js, revokeToken.js, ragProcess.js, webScraping.js are byte-identical in both repos. A change in only one creates drift. |
Bug exists in helper/X.js that doesn't exist in someli-api/helper/X.js |
They've drifted — read both before fixing |
Schema change in someli-api broke an admin endpoint |
The DB is shared; coordinate changes |
| Reference |
../../audit/CODE-OVERLAP-MATRIX.md, ../../audit/Someli-admin-api/code-overlap.md |
Email / notifications
| Symptom |
First place to look |
| Email not sent |
SENDGRID_API_KEY, FROM; sendgrid calls in routes/auth.js and routes/routes.js |
| Slack notification missing |
Hardcoded token in routes/auth.js (known finding) |
Deployment / infra
| Symptom |
First place to look |
| No Dockerfile |
This repo doesn't have one. Production hosting strategy is opaque from the repo — ask the team |
| Deploy doesn't reflect changes |
No in-repo CI — ask the team |
| Reference |
../../audit/Someli-admin-api/build-and-deploy.md |
The Python batch processor (Nova-Pro_KnowledgeBased_Content.py)
| Symptom |
First place to look |
| It crashes |
Run it with python3 directly; Bedrock credentials in boto3 config |
| Changes to it have no effect on the Node server |
Correct — it's a separate runtime, invoked separately |
When all else fails