The whole system

Product pages reach the backend through one client, src/lib/api.ts, which attaches the access token. On the backend, main.ts sets the /api prefix and hands the phone provider's WebSocket upgrades to the realtime gateway. Every other request passes the global AuthGuard into a feature module, and every module stores data through MongoService.

Who can call what

The guard is registered globally, so every route is private unless it opts out with @Public(). Opting out does not mean unchecked. Routes the phone provider calls carry their own proof instead of a user token.

Which module does what

Each feature is a NestJS module under AgentReach-backend/src. The kind says how work reaches it: a REST route, a provider webhook, a media socket or a cron job.

One outbound call, end to end

A calling campaign holds one CallHistory row per contact. Launching it dials each contact in turn. The conversation runs later, on the realtime gateway, which bridges the phone line to a Gemini Live session.

When a signal sends email on its own

Three collectors poll each active company watch every six hours: news RSS, SEC EDGAR and job boards. Operators can also add signals by hand or post SES bounces. Every signal then goes through IngestionService.ingest(), and only a narrow case sends email without a person approving it.

Where the data lives

MongoService wraps 16 Mongoose models in Prisma-style delegates such as findMany, findUnique, create and update, and maps Mongo's _id to id. Services read like a relational client while MongoDB stays the store. All accounts share one workspace, which is why sign-up is closed in production unless ALLOW_REGISTRATION is set.

Background work

Two cron jobs and two kinds of in-process work run outside any request. None of them is a separate worker; they share the backend process.

Why it is built this way

• Provider keys live in the database.

  Settings encrypts them with AES-256-GCM before saving and always returns them masked. Operators change keys without a redeploy; GEMINI_API_KEY in the environment is only a fallback.

• Webhooks are public but signed.

  Twilio and Plivo cannot send a user token, so each callback URL carries an HMAC of its call id, keyed with JWT_SECRET. A forged URL gets a 403.

• Gemini is checked before the phone rings.

  The preflight session catches a bad key or model on the call row, so a contact never answers into silence.

• One gateway, two phone providers.

  Both providers stream μ-law 8 kHz in the same event envelope. Only the outbound audio, clear and mark frames branch on the provider.

• Bot knowledge is embedded locally.

  Chunks become 384-dimension hashed word vectors, so training and fetch_context make no API call and stay fast enough for a live call. The trade-off is keyword recall rather than semantic search.

• Signals only send on their own for the strongest match.

  An email-domain match under an auto playbook fires. Anything weaker waits for a person, and repeated rejections suppress the pairing.

• Launching twice never double-sends.

  A second launch retries only FAILED recipients. Re-sending to everyone, including those already SENT, is a separate relaunch the operator has to choose.

Run it yourself

Each app runs on its own. The backend needs MongoDB and a JWT secret; provider keys are entered later in Settings.

# Backend: REST on :3001/api, Swagger on :3001/docs
cd AgentReach-backend
npm install
cp .env.example .env      # set DATABASE_URL and JWT_SECRET
npm run start:dev

# Frontend: app on :3000, these docs on :3000/documentation
cd AgentReach-frontend
npm install
# in .env.local: NEXT_PUBLIC_API_URL=http://localhost:3001/api
npm run dev

File map