Cclarity Backend

Getting Started

1. Run project

1.1. Install required packages

Use following command to install all required packages

npm install

1.2. Places configurations files to correct places

Obtain required files from other developers

• .env
• config/database.json
• config/whitedlist.json

Optional: Slack notifications for inbound LinkedIn replies

If you want Slack alerts when receiving messages via Unipile webhook, add this to your .env:

• SLACK_WEBHOOK_URL=<your_slack_incoming_webhook_url>

You can test it (after npm run build) with:

• curl -X POST -H "Content-type: application/json" --data '{"text":"Slack webhook test"}' "$SLACK_WEBHOOK_URL"

Optional: Voice Clara transcript ingest endpoint

If you want to accept transcript sync calls from voice-call-clara, add this to your .env:

• VOICE_CLARA_API_KEY=<shared_secret_used_by_voice_app>

This key is validated by the backend middleware on:

• POST /api/voice-clara/end-call

1.3. Run the service locally

Use following command to run the service locally

npm run start:dev

It will run project locally, should see following logs in console

config /Users/khanhtruong/Documents/Repositories/jdi/cclarity-be/config/s3.json
(node:78930) NOTE: We are formalizing our plans to enter AWS SDK for JavaScript (v2) into maintenance mode in 2023.

Please migrate your code to use AWS SDK for JavaScript (v3).
For more information, check the migration guide at https://a.co/7PzMCcy
(Use `node --trace-warnings ...` to show where the warning was created)
Socket on
runInit
App is listening at port 8080 (HTTP)
RUN PENDING SCHEDULE POST SUCCESSFULLY postId: 664b0d906a30b213a59a1ed4 scheduleId: 664b0d906a30b213a59a1ed5 publishedAt: 2024-10-31T21:00:00.000Z
RUN PENDING SCHEDULE POST SUCCESSFULLY postId: 6652de88b8d6be20073ad380 scheduleId: 6654aab5b8d6be20073ad3a1 publishedAt: 2025-05-30T01:36:00.000Z

Then service will be ready to use at http://localhost:8080

1.4. Build and package for deployment

npm run build
zip -r dist.zip dist  

# MossOwl Production
zip -r "cclarity-be-no-config-no-node_modules.zip" . -x "node_modules/*" "*/node_modules/*" "node_module/*" "*/node_module/*" "config/*" "cclarity-be-no-config-no-node_modules.zip" ".env" "*/.env"

1.5 Deploy to EC2 instance

Should contact other developers to obtain *.pem for ssh connect to Staging/Production EC2 instances.

Use following command to copy the dist.zip from step 1.4, please note that it has the IP address of instances. If in the situation, the IP address has changed, then need to update accordingly.

# Staging
scp -i cclarityBEStaging.pem dist.zip [email protected]:/home/ubuntu/cclarity-be-staging/dist.zip

# Production
scp -i cclarityBEProduction.pem dist.zip [email protected]:/home/ubuntu/cclarity-be-production/dist.zip

# MossOwl Production
scp -i cclarityBEMossOwlProduction.pem dist.zip [email protected]:/home/ubuntu/moss-owl-be-production/dist.zip

scp -i cclarityBEMossOwlProduction.pem cclarity-be-no-config-no-node_modules.zip [email protected]:/home/ubuntu/moss-owl-be-production/cclarity-be-no-config-no-node_modules.zip

Please note, need to upload other files if the change involves

• package changes: upload package.json file
• configuration files changes in /config: upload corresponding files into /config directory

1.6 Connect and manages files

To connect, use same *.pem files

# Staging
ssh -i cclarityBEStaging.pem [email protected]

# Production
ssh -i cclarityBEProduction.pem [email protected]

# MossOwl Production
ssh -i cclarityBEMossOwlProduction.pem [email protected]

Unzip the dist.zip into correct directory (either cclarity-be-staging or cclarity-be-production), choose All when ask whether user want to override existing files

unzip dist.zip

# MossOwl Production
unzip cclarity-be-no-config-no-node_modules.zip

1.7 Manage backend service in EC2 instances

Current implementation uses PM2 to run services, some common commands

1.7.1 List services

pm2 ls

It will print out log of running services. Example logs from Staging environment

ubuntu@ip-172-31-29-30:~$ pm2 ls
┌────┬────────────────────┬─────────────┬─────────┬─────────┬──────────┬────────┬──────┬───────────┬──────────┬──────────┬──────────┬──────────┐
│ id │ name               │ namespace   │ version │ mode    │ pid      │ uptime │ ↺    │ status    │ cpu      │ mem      │ user     │ watching │
├────┼────────────────────┼─────────────┼─────────┼─────────┼──────────┼────────┼──────┼───────────┼──────────┼──────────┼──────────┼──────────┤
│ 0  │ backend-staging    │ default     │ N/A     │ fork    │ 480782   │ 91m    │ 110  │ online    │ 0%       │ 73.1mb   │ ubuntu   │ disabled │
│ 1  │ stripe             │ default     │ N/A     │ fork    │ 309592   │ 2M     │ 0    │ online    │ 0%       │ 18.1mb   │ ubuntu   │ disabled │
└────┴────────────────────┴─────────────┴─────────┴─────────┴──────────┴────────┴──────┴───────────┴──────────┴──────────┴──────────┴──────────┘

We can use either id or name to manage services with commands reload, stop, logs

1.7.2 Reload/Restart service

pm2 reload 0

or

pm2 reload backend-staging

1.7.3 Run service

pm2 start "npm start" --name backend-staging --log-date-format="YYYY-MM-DD HH:mm Z"

Please note in Staging, we also need to have a webhook service for Stripe to run. This is not required by Production

pm2 start stripe --name stripe listen -- listen --forward-to http://localhost:8080/api/stripe/webhook

1.7.4 Troubleshoot service

Use following commands in Staging to see error logs

• Can remove --err to see all type of logs
• Can also use id like 0 rather service name
• Can change amount of lines from 1000 to any necessary numeric numbers

pm2 logs backend-staging --err --lines 1000

Same principles apply for Production environment

Documentation

MCP CLI (npm)

The terminal client is published as @cclarity-packages/cli. Source lives in cli/ in this repo.

cd cli
npm install
npm test
npm publish   # requires npm org @cclarity-packages + publish rights; see cli/README.md

• Install (users): npm install -g @cclarity-packages/cli or npx @cclarity-packages/cli login
• Binary: cclarity (after global install)
• Docs: cli/README.md, docs/mcp/MCP-CLI.md, docs/mcp/MCP-CONNECTOR-ACCESS.md

Backend Documentation

• LinkedIn data mirroring to users: docs/linkedin-data-mirroring.md

Frontend Integration Guides

• Stale-While-Revalidate Pattern: docs/FRONTEND_INTEGRATION_STALE_WHILE_REVALIDATE.md
  • Instant response times for relation sync (<100ms)
  • WebSocket-based real-time updates
  • Complete implementation guide with React and Vue examples