Agency CRM Full System Documentation

Agency CRM lead generation, email outreach, reply tracking, meeting automation, AI email coordination, landing page, login, and profile settings ka complete system hai.

Node.js + Express Login Protected CRM Encrypted Profile Settings Apollo + LeadGorilla OpenAI Email AI Mobile Responsive

1. Overview 2. Features 3. Lead Workflow 4. Profile Settings 5. OpenAI Automation 6. Email System 7. Reply + Meeting Automation 8. API Routes 9. Deployment 10. Troubleshooting 11. Important Files 12. Notes

1. Overview

Backend server.js Express par run hota hai, frontend index.html, css/style.css, aur js/app.js se browser mein chalta hai. Data JSON files mein store hota hai.

System public landing page show karta hai. Dashboard access sirf login ke baad milta hai. Default login pehli dafa admin / admin123 hai, jise Profile Settings se change karna chahiye.

Latest system mobile responsive hai: dashboard, pipeline, tables, settings, modals aur landing page mobile par adjust hote hain.

2. Features

Landing Page + Login

Public landing page modules show karta hai. Dashboard login ke baghair hidden rehta hai.

Profile Settings

Portal name, slogan, logo, super admin ID/password aur API settings manage hoti hain.

Encrypted API Settings

Apollo, LeadGorilla, OpenAI, Gmail, SMTP, IMAP values encrypted portal_secrets.json mein save hoti hain.

Apollo Fetch

Job title, country, company size aur keywords ke base par Apollo API se leads fetch hoti hain.

LinkedIn Intent Leads

Marketing agency, SEO, website, ads related post intent se leads create karne ka module available hai.

LeadGorilla

Business/local lead search ke liye LeadGorilla API integration ready hai.

CSV Import / Export

Leads CSV se import aur export ho sakti hain.

Manual Lead Add

Name, email, phone, website, company, source, service aur requirements/comments ke sath lead add hoti hai.

Pipeline

Stages: New Lead, Contacted, Replied, Meeting, Proposal, Won. Forward/backward stage movement available hai.

Meeting Calendar

Meeting stage mein schedule/reschedule button se manual date/time set kar sakte hain.

OpenAI Coordination

AI client reply samajh kar email draft, intent aur next action suggest/send kar sakta hai.

Fallback Safe

OpenAI fail ho to old template/keyword system automatically chalta rehta hai.

3. Lead Workflow

Lead Apollo, LinkedIn, LeadGorilla, CSV import ya manual form se system mein aati hai.
Duplicate email/API id check hota hai.
Lead New Lead stage mein save hoti hai.
Profile setting First Email Auto Send on ho to first email background mein send hoti hai.
Profile mein OpenAI Automation on ho to email personalized draft hoti hai; off/fail ho to normal saved template email send hoti hai.
Email send hone par lead Contacted stage mein move hoti hai.
Client reply kare to IMAP reply processor reply timeline mein save karta hai.
OpenAI reply intent samajhta hai; fallback keyword logic bhi active rehta hai.
Meeting intent ho to lead Meeting stage mein jati hai. Requested time free ho to unique meeting link generate hota hai.
Requested meeting time already booked ho to client ko multiple available time options email hoti hain. Client option select/done/confirmed reply kare to meeting link generate hota hai.
Pricing/proposal reply ho to lead Proposal stage mein jati hai.
Proposal sent hone ke baad client go ahead/onboarding/approved type reply kare to lead Won stage mein move hoti hai.
Non-meeting replies par AI draft timeline mein save hoti hai; optional auto-send setting bhi available hai.

4. Profile Settings

Profile Settings dashboard ke sidebar mein available hai. Is section mein portal branding, login credentials aur encrypted integrations manage hoti hain.

Section	Fields	Notes
Portal Profile	Portal Name, Slogan, Logo Text, Logo URL	Landing page, sidebar aur browser title update hota hai.
Super Admin Login	Admin ID, current password, new password	Password change ke liye current password required hai.
Lead APIs	Apollo, LeadGorilla, PhantomBuster	Secret values masked hoti hain; blank chorne se old value keep rehti hai.
AI Automation	OpenAI On/Off, OpenAI API Key, OpenAI Model, AI Auto Send Replies	OpenAI key encrypted save hoti hai. Off mode mein normal templates chalte rehte hain.
Email	Gmail, custom SMTP, TLS settings, From/Reply-To	Gmail ya company SMTP dono supported hain.
Replies	IMAP host, port, user, pass	Client replies read karne ke liye.
Automation	First Email Auto Send, cron, daily limit, delay	First email on/off yahin se control hoti hai.
Meetings	Meeting base URL	Unique meeting links ke liye.

Encrypted files portal_secrets.json aur portal_secret.key ko server par safe rakhna hai. portal_secret.key delete ho gaya to old encrypted values decrypt nahi hongi.

5. OpenAI Automation

OpenAI integration emails ko client context aur reply ke mutabiq coordinate karta hai.

Setting	Recommended	Purpose
`OPENAI_API_KEY`	Your key	OpenAI API access.
`OPENAI_MODEL`	`gpt-5.4-mini`	Email drafting and reply classification.
`AI_EMAIL_AUTOMATION`	`true` or Profile toggle On	On par first/follow-up emails AI personalize karega. Off par normal saved templates use honge.
`AI_AUTO_SEND_REPLIES`	`false`	False par AI draft banata hai; true par non-meeting replies auto-send kar sakta hai.

AI Flow

New lead email: AI lead company/service/source ke hisab se email personalize karta hai.
Follow-up email: scheduler AI se short contextual follow-up generate karta hai.
Client reply: AI intent classify karta hai: meeting, reschedule, pricing/proposal, approved/onboarding/won, interested, question, not interested, unsubscribe.
AI draft: lead modal/timeline mein Send AI Draft button ke sath show hoti hai.
OpenAI off/fail ho to normal template email aur keyword classifier automatically use hota hai.

Safe mode ke liye AI_AUTO_SEND_REPLIES=false rakhein. Is mode mein AI sirf draft banayega, email aap button se send karenge.

6. Email System

First Email: New manual/import/source lead par background mein send hoti hai, agar Profile mein First Email Auto Send on ho.
Follow-up Emails: EMAIL_CRON aur template delay ke mutabiq send hoti hain.
Manual Send: Outreach Center se selected lead ko next email send kar sakte hain.
Templates: Plain text, HTML aur CSS templates editable hain.
Reply-To: Gmail reply-to setup supported hai.

Gmail SMTP blocked/proxy ho to company SMTP use karein: EMAIL_PROVIDER=smtp, SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS.

Certificate mismatch aaye to hosting SMTP settings check karein. Temporary bypass SMTP_TLS_REJECT_UNAUTHORIZED=false hai, lekin production mein valid certificate better hai.

7. Reply + Meeting Automation

Reply processor IMAP inbox se replies read karta hai, lead email se match karta hai, aur timeline mein body/subject/from/date save karta hai.

Reply Intent	System Action
Meeting, call, schedule, available	Stage Meeting, requested time parse, conflict check. Free slot par meeting link + confirmation email.
Same time already booked	Client ko multiple available slots email. Link tabhi send hota hai jab client option select/done/confirmed reply kare.
Reschedule	Stage Meeting, pending/manual schedule option.
Pricing/proposal	Stage Proposal, proposal dropdown se PDF send.
Proposal approved/go ahead/onboarding	Stage Won, sent proposal PDF timeline/card se view ho sakti hai.
Question/interested	Stage Replied, AI draft can be created.
Unsubscribe/not interested	Lead unsubscribed, follow-up stops.

Meeting stage mein pipeline card par confirmed meeting time/link show hota hai. Pending multiple time options ke liye timeline mein reschedule proposal record save hota hai.

8. API Routes

Route	Method	Purpose
`/api/public-settings`	GET	Landing/login branding.
`/api/auth/login`	POST	Super admin login.
`/api/auth/logout`	POST	Logout session.
`/api/settings`	GET/PUT	Portal profile and login settings.
`/api/settings/secrets`	GET/PUT	Encrypted API/SMTP/OpenAI settings.
`/api/status`	GET	Server, Apollo, SMTP, schedulers, reply poller status.
`/api/leads`	GET/POST	List/add leads.
`/api/leads/:id`	PUT/DELETE	Update/delete one lead.
`/api/leads/import-csv`	POST	CSV leads import.
`/api/leads/:id/send-email`	POST	Selected lead ko next email send.
`/api/leads/:id/ai-draft`	POST	Latest client reply ke mutabiq AI draft create.
`/api/leads/:id/send-ai-draft`	POST	Saved AI draft send.
`/api/leads/:id/schedule-meeting`	POST	Manual meeting schedule/reschedule.
`/api/apollo/fetch`	POST	Apollo leads fetch.
`/api/linkedin/scrape`	POST	LinkedIn intent leads.
`/api/leadgorilla/search`	POST	LeadGorilla search.
`/api/sources/run`	POST	All lead sources run.
`/api/replies/run`	POST	Replies manually sync.
`/api/templates`	GET/PUT	Email templates load/save.

9. Deployment

npm install
node server.js

Production mein PM2 recommended hai:

npm install -g pm2
pm2 start server.js --name agency-crm
pm2 save

Deploy ke baad latest files upload karke Node process restart karein.
Frontend same domain par backend /api call karta hai.
Test URL: https://your-domain.com/api/status
Agar Cannot POST /api/auth/login aaye to server old code chala raha hai; process restart karein.

10. Troubleshooting

Issue	Reason	Solution
Cannot POST /api/auth/login	Old server process running.	Latest files upload karein aur `node server.js`/PM2 restart karein.
OpenAI email nahi ban rahi	OpenAI toggle off, key/model/quota/network issue.	Profile > AI Automation mein toggle/key check karein. Off/fail ho to normal template email automatically send hoti rahegi.
First email nahi jati	First Email Auto Send off, email missing, SMTP issue.	Profile Automation mein setting on karein, SMTP verify karein.
Apollo error	API key missing/invalid.	Profile Lead APIs mein Apollo key save karein.
Email certificate mismatch	Hosting SMTP proxy/cert mismatch.	Company SMTP host use karein ya hosting support se outbound Gmail SMTP allow karwayen.
Replies update nahi hoti	IMAP missing/wrong, reply from different email.	Profile Replies settings check karein aur Sync Replies run karein.
Meeting conflict ignored	Old process or missing booked meeting times.	Server restart karein, existing leads mein `meetingAtIso` records check karein.
Conflict par direct link chali gai	Old code running.	Latest `replyProcessor.js` upload karke Node/PM2 restart karein. New flow pehle alternate time approval email bhejta hai.

11. Important Files

index.html

Landing, login, dashboard layout and tab containers.

css/style.css

Responsive styling for landing, dashboard, tables, pipeline and modals.

js/app.js

Frontend API calls, rendering, settings UI, AI draft buttons, modals.

server.js

Express API, auth, settings, routes, source/email/reply startup.

openaiService.js

OpenAI Responses API wrapper, email draft and reply intent logic.

emailService.js

Gmail/custom SMTP transporter and send email logic.

emailScheduler.js

Scheduled follow-up batch emails with AI fallback.

replyProcessor.js

IMAP reply sync, AI reply analysis, meeting automation.

leads_data.json

Lead database.

templates_custom.json

Editable email templates.

portal_settings.json

Portal branding and login settings.

portal_secrets.json + portal_secret.key

Encrypted API/SMTP/OpenAI settings and encryption key.

12. Notes

.env, portal_secrets.json, portal_secret.key public repo mein upload na karein.
OpenAI toggle off ya key fail ho to system normal saved template and keyword logic par fallback karta hai.
AI_AUTO_SEND_REPLIES=false safe recommended setting hai.
Large lead volume ke liye JSON storage ke bajaye database recommended hoga.
Server restart ke bina new env/process-level config apply nahi hoti; Profile secrets save hone par runtime env update ho jata hai.
Reply automation tabhi accurate hogi jab lead email aur client reply sender same ho.