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 Gemini Email AI Mobile Responsive

1. Overview 2. Features 3. Lead Workflow 4. Profile Settings 5. Gemini 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, Gemini, 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.

LeadGorilla

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

CSV Import / Export

Leads CSV se import/export hoti hain. Import common headers auto-map karta hai: full name, company, phone/WhatsApp, email, website, source aur service required.

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.

Gemini Coordination

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

Fallback Safe

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

3. Lead Workflow

Automation ko development ke liye 5 simple lanes mein rakha gaya hai. Har lane ka rule clear hai, taake bugs trace karna easy ho.

Lane	Automatic Rule	Manual Rule
Lead Intake	Apollo, LeadGorilla, CSV ya manual lead save hoti hai. CSV import common headers auto-map karta hai: full name, company, phone/WhatsApp, email, website, source aur service required. Duplicate email/API id skip hota hai.	Missing/incorrect fields All Leads se edit honge.
First Outreach	First Email Auto Send on ho to new valid-email lead par AI Decision Engine lead/source/service/website analyze karta hai aur best angle choose karta hai: website audit, website layout, social media audit/planning, SEO strategy, 360 marketing ya ecommerce development. Stage `Contacted` hota hai.	First Email Auto Send off ho to Outreach/All Leads se manual send.
Replies	IMAP reply timeline mein save hota hai. AI intent + keyword fallback stage decide karta hai.	Confusing reply par AI draft/manual stage buttons use karein.
Meetings	Meeting/call intent par stage `Meeting`. Time missing ho to availability ask email. Time booked ho to options email. Confirmed option par final meeting link.	Pipeline Meeting card se schedule/reschedule manually.
Proposals/Won	Pricing/proposal reply par stage `Proposal`. Client approval only after sent proposal moves to `Won`.	Proposal PDF hamesha manually send hota hai.

Development safety: run npm run test:automation after automation changes. Ye reply intent, proposal-to-won guard, meeting conflict slots, pending option selection aur reply cleanup verify karta 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 Upload, Favicon/PDF Icon Upload	Landing page, sidebar, browser icon aur proposal PDF branding update hoti hai.
Super Admin Login	Admin ID, current password, new password	Password change ke liye current password required hai.
Lead APIs	Apollo, LeadGorilla	Secret values masked hoti hain; blank chorne se old value keep rehti hai.
AI Automation	Gemini On/Off, Gemini API Key, Gemini Model, AI Auto Send Replies	Gemini 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. Gemini Automation

Gemini integration emails ko client context aur reply ke mutabiq coordinate karta hai. API key Google AI Studio se milti hai.

Setting	Recommended	Purpose
`GEMINI_API_KEY`	Your Gemini key	Gemini API access.
`GEMINI_MODEL`	`gemini-2.5-flash-lite`	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 Decision Engine lead context se service angle choose karta hai aur usi angle ka email/PDF send karta hai. Web design lead ko business category ke mutabiq landing page design concept PDF milta hai. SEO lead ko website SEO audit report PDF milti hai. Ye proposal ya company profile nahi hota.
Follow-up email: scheduler saved aiServiceAngle aur aiFollowupPlan ke mutabiq 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.
Gemini 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 smart first email 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.

AI Decision Engine

Chosen Angle	Email Type	Attachment
Website Design	Landing page design concept outreach	`{company}-website-layout-concept.pdf`
SEO	Website SEO audit report outreach	`{company}-seo-audit-report.pdf`
General website context	Website audit outreach	`{company}-website-seo-audit.pdf`
Social / 360 / Ecommerce	Service-specific pitch and follow-up lane	`{company}-social-media-audit.pdf`, `{company}-social-media-strategy-design.pdf`, `{company}-360-marketing-plan.pdf`, `{company}-ecommerce-development-plan.pdf`

Decision saved fields: websiteAudit, websiteAuditSummary, websiteAuditIssues, websiteSocialLinks, aiServiceAngle, aiOfferType, aiReason, aiConfidence, aiFollowupPlan. Website ho to system page open karke status, speed signal, title, meta description, headings, canonical, viewport, schema, image alt issues aur social links scan karta hai. PDF mein actual findings, priority issues aur business-category strategy include hoti hai. Screenshot Playwright available ho to capture hota hai; warna screenshot status show hota hai. Smart first attachment proposal/company profile se alag hoti hai.

First Email Auto Send + Gemini Rule

First Email Auto Send	Gemini Automation	Result
On	On	Smart first email automatically send hoti hai. Content Gemini personalize karta hai, attachment system choose karta hai.
On	Off/fail	Smart first email automatically send hoti hai. Built-in audit/layout body aur PDF use hota hai.
Off	On	First email automatically nahi jati. Manual send par Gemini content/draft generate kar sakta hai.
Off	Off	First email automatically nahi jati. Manual send par saved template use hota hai.

Final gatekeeper First Email Auto Send hai. Ye off ho to Gemini on hone ke bawajood new lead par first email khud se nahi jati.

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/Gemini 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/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.
Gemini email nahi ban rahi	Gemini 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

Gemini 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/Gemini settings and encryption key.

12. Notes

.env, portal_secrets.json, portal_secret.key public repo mein upload na karein.
Gemini 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.