Skip to content

04 — Your first contribution to Someli-admin-api

A walkthrough.

1. Pick a small first task

Good first tickets:

  1. Doc fix in ../../audit/Someli-admin-api/.
  2. A console.log cleanup from ../../code-inspect/Someli-admin-api.md.
  3. Add a validator chain to a routes/routes.js endpoint that currently accepts unvalidated input.
  4. Sync a byte-identical helper. Open someli-api/helper/tokenGenerator.js and Someli-admin-api/helper/tokenGenerator.js — confirm they're still byte-identical (the audit was at 2026-05-17; they may have drifted since). Open a PR pair if you find drift.
  5. Move the hardcoded session secret to an env var. server.js:58 hardcodes secret: "3eB(2:\srlI+qa5". Change to secret: conf.SESSION_SECRET || 'change-me', add SESSION_SECRET to conf.js and .env.

Avoid for your first PR: anything inside helper/aiLogics.js (drift surface), the Python batch processor, anything spanning the two auth layers.

2. The edit-run-verify loop

cd ~/src/someli/Someli-admin-api

# Branch
git checkout dev
git pull origin dev
git checkout -b fix/first-pr

# Run
yarn start                            # nodemon

# Verify
curl -i http://localhost:5004/<endpoint>

No /health endpoint — pick a known endpoint from ../../audit/Someli-admin-api/API-inventory.md for smoke tests.

3. Entry points to know — a 20-minute reading tour

  1. server.js (70 lines). Read entirely.
  2. methods.js (16 lines). The Bearer-JWT middleware. Read entirely.
  3. middlewares/auth.js. The encrypted-Bearer middleware. Read entirely.
  4. routes/routes.js (1400 lines) — scroll through. Note where methods.ensureToken is added and where it's absent.
  5. routes/auth.js (957 lines) — scroll. Notice router.use(auth) at the top.
  6. helper/tokenGenerator.js — short. Read.
  7. actions/actions.js — the CRUD layer. Skim.

4. Reading-around your task

  1. Grep: 
    grep -n 'mySearchTerm' routes/routes.js routes/auth.js
grep -ln 'mySearchTerm' helper/*.js middlewares/*.js
  2. Check overlap with someli-api: 
    diff someli-api/helper/<file>.js Someli-admin-api/helper/<file>.js
  3. Audit docs:
  4. Auth → ../../audit/Someli-admin-api/authentication.md
  5. API inventory → ../../audit/Someli-admin-api/API-inventory.md
  6. Code overlap → ../../audit/Someli-admin-api/code-overlap.md

5. Manual testing

No test suite.

For a new endpoint:

  1. Hit it via curl with a valid token.
  2. Hit it without a token (expect 401).
  3. Hit it with a malformed body (expect 400 if you added a validator).
  4. Use the admin FE (admin_console_R running locally) pointed at your local backend.

6. Useful local helpers

Scratch script

// scratch.js (gitignored)
require('dotenv').config();
const { decryptToken } = require('./helper/tokenGenerator');
console.log(decryptToken("..."));

Talking to the DB

Same as the rest of the platform. Be careful — admin endpoints typically read/modify all users' data. Don't run experimental SQL on production.

7. Opening the PR

git add -p
git commit -m "Add SESSION_SECRET env var; remove hardcoded session secret"
git push -u origin fix/first-pr
# Open PR on github.com/Someli-ai/Someli-admin-api → dev

PR description:

  • Why / what
  • Manual test plan
  • New env vars (if any) — call out at the top
  • Whether the change applies to someli-api too — if you touched a byte-identical helper, the answer is yes

8. After merge

No in-repo CI. Ask the team how the dev deploy works.

git checkout dev && git pull
git branch -d fix/first-pr

9. Common first-PR mistakes

Mistake Why it bites Avoid by
Editing helper/tokenGenerator.js without updating someli-api/helper/tokenGenerator.js The two diverge silently — and they're security-critical Always update both in the same PR pair
Mixing the two auth layers in one PR Easy to forget which auth a new endpoint uses Decide upfront: encrypted-Bearer (→ routes/auth.js) or plain JWT (→ routes/routes.js + methods.ensureToken)
Adding a webhook handler without confirming the bodyparser exemption Express has already JSON-parsed the body; signature verification fails The exemption is already in server.js for stripe/paddle paths — confirm yours is on that list
Forgetting Someli-admin-api shares MySQL with someli-api Schema changes break the other repo Coordinate schema changes
Editing the Python file It's a separate runtime — your Node yarn start won't reflect changes Treat the Python file as a separate sub-project

Next

→ 05-where-to-look.md.