# ClientScout AI ClientScout AI is a private, Appwrite-backed CRM for manually managing leads, follow-ups, notes, verification, and CSV import/export. This repository implements **Phase 1 only**: - Secure sign-in - Protected CRM dashboard - Manual lead CRUD - CSV import/export - Activity history - Personal settings - Responsive desktop and mobile UI Phase 2 groundwork is now in place for: - Deterministic normalization helpers - Duplicate detection utilities - Safe website-audit SSRF protections - Verification scoring scaffolding - Appwrite bootstrap support for Phase 2 collections It does **not** implement: - Automatic lead discovery - Web scraping - AI integrations - Website auditing - Automated outreach - Demo website generation - Public signup ## Tech Stack - Next.js 16 App Router - TypeScript strict mode - Tailwind CSS - Appwrite Cloud - Zod - React Hook Form - Papa Parse - date-fns - Sonner ## Folder Structure - `src/app` - routes, layouts, API routes - `src/components` - reusable UI and CRM components - `src/features` - feature-specific client components - `src/lib` - Appwrite, validation, scoring, CSV, and services - `src/types` - shared domain types - `scripts` - setup automation - `src/lib/**/*.test.ts` - Vitest tests ## Environment Variables Create `.env.local` from `.env.example`: ```env NEXT_PUBLIC_APPWRITE_ENDPOINT= NEXT_PUBLIC_APPWRITE_PROJECT_ID= NEXT_PUBLIC_APPWRITE_DATABASE_ID= NEXT_PUBLIC_APPWRITE_LEADS_COLLECTION_ID= NEXT_PUBLIC_APPWRITE_ACTIVITY_COLLECTION_ID= NEXT_PUBLIC_APPWRITE_SETTINGS_COLLECTION_ID= NEXT_PUBLIC_APPWRITE_VERIFICATION_COLLECTION_ID= NEXT_PUBLIC_APPWRITE_WEBSITE_AUDITS_COLLECTION_ID= NEXT_PUBLIC_APPWRITE_OUTREACH_COLLECTION_ID= NEXT_PUBLIC_APPWRITE_FOLLOWUPS_COLLECTION_ID= CLIENTSCOUT_WEBSITE_AUDIT_TIMEOUT_MS=10000 CLIENTSCOUT_WEBSITE_AUDIT_MAX_BYTES=1500000 CLIENTSCOUT_WEBSITE_AUDIT_MAX_REDIRECTS=5 CLIENTSCOUT_AUDIT_RATE_LIMIT_PER_MINUTE=10 APPWRITE_API_KEY= ``` Rules: - `APPWRITE_API_KEY` is server-only. - Do not expose any privileged key through `NEXT_PUBLIC_*`. - The app validates required variables at startup. ## Appwrite Setup ### Recommended resources - Database: `clientscout_db` - Collection / table IDs: - `cs_leads` - `cs_activity_logs` - `cs_settings` - `cs_assets` - Phase 2 collection IDs: - `cs_verification_evidence` - `cs_website_audits` - `cs_outreach_drafts` - `cs_follow_ups` - Required user label: `clientscoutaccess` ### First user Public signup is disabled. Create the first Appwrite user manually in the Appwrite Console, then assign the `clientscoutaccess` label to that user before signing in. If your Appwrite SDK/project does not expose label-management methods to the setup script, create the label manually in the Console and apply it to the user there. ### Setup script Run: ```bash npm run setup:appwrite ``` The script is designed to be idempotent and non-destructive: - It checks exact resource IDs before creating anything - It creates missing database, collections, attributes, and indexes - It aborts instead of modifying incompatible existing resources Phase 2 setup now also provisions the verification, website-audit, outreach, and follow-up collections when they are missing. ## Local Setup 1. Install dependencies 2. Copy `.env.example` to `.env.local` 3. Fill in Appwrite endpoint, project ID, and API key 4. Run the Appwrite setup script 5. Start the dev server ```bash npm install npm run setup:appwrite npm run dev ``` ## Development Server ```bash npm run dev ``` ## Tests ```bash npm test ``` Tests cover: - Lead score calculation - Priority calculation - Phone normalization - URL normalization - Duplicate detection - Lead schema validation - Phase 2 normalization helpers - Duplicate detection helpers - Website audit safety checks ## Production Build ```bash npm run build ``` ## Vercel Deployment 1. Push this repository to GitHub 2. Import the project into Vercel 3. Add the environment variables from `.env.example` 4. Set the same Appwrite endpoint and project ID used locally 5. Deploy If you use a custom domain for Appwrite, make sure the project is configured consistently for browser sessions. ## CSV Import Format Supported columns include: - `businessName` - `contactPerson` - `industry` - `businessType` - `country` - `city` - `timezone` - `phone` - `whatsapp` - `email` - `website` - `instagram` - `linkedin` - `facebook` - `otherSocialUrl` - `sourceName` - `sourceUrl` - `sourceNotes` - `websiteStatus` - `contactVerification` - `verificationConfidence` - `verificationNotes` - `mainOpportunity` - `recommendedService` - `status` - `priority` - `notes` - `lastContactedAt` - `nextFollowUpAt` - `demoUrl` The import flow: - uploads a CSV - maps columns - previews rows - flags invalid rows - flags possible duplicates - imports selected rows ## Security Notes - Appwrite API keys never go to the browser - Protected routes require an authenticated JWT cookie - Row/document permissions are owner-scoped - Only users with `clientscoutaccess` can sign in - No automatic sending or unsafe script execution is included ## Phase 1 Limitations This release intentionally stops at manual CRM operations. Not included yet: - AI lead generation - scraping or crawling - website audits - outreach automation - demo site generation - public signup flow - configurable scoring editor ## Planned Future Phases - Lead discovery and enrichment - Website analysis and reporting - AI-assisted outreach drafting - Demo site generation - Conversion tracking and pipeline automation # ClientScout-AI # ClientScout-AI # ClientScout-AI