# Quick Start Guide Get started with CiteFlow in 5 minutes to track AI bot activity on your website. ## Prerequisites - Node.js 20+ - PostgreSQL database - npm or yarn ## Installation ### 1. Clone and Install ```bash git clone https://github.com/yourusername/citeflow.git cd citeflow npm install ``` ### 2. Configure Environment Create a `.env.local` file: ```env # Database DATABASE_URL="postgresql://postgres:password@localhost:5432/citeflow" # Clerk Authentication (optional) NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="your_key" CLERK_SECRET_KEY="your_key" # Stripe (optional) STRIPE_SECRET_KEY="your_key" STRIPE_WEBHOOK_SECRET="your_key" # App URL NEXT_PUBLIC_APP_URL="http://localhost:3000" ``` ### 3. Initialize Database ```bash npx prisma migrate deploy npx prisma generate ``` ### 4. Start Server ```bash npm run dev ``` Visit http://localhost:3000 ## Add Your First Site ### Step 1: Create Account Sign up and verify your email. ### Step 2: Add Site 1. Go to Dashboard → Settings 2. Enter your website domain 3. Get your site ID ### Step 3: Install Tracker Add this to your website's ``: ```html ``` ### Step 4: Set Up Bot Tracking (Recommended) For real-time AI bot tracking, deploy our Cloudflare Worker: ```javascript export default { async fetch(request, env, ctx) { const userAgent = request.headers.get("user-agent") || ""; const referer = request.headers.get("referer") || ""; ctx.waitUntil( fetch("http://localhost:3000/api/bot-visits", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ siteId: env.CITEFLOW_SITE_ID, url: request.url, userAgent: userAgent, referer: referer, secFetchSite: request.headers.get("sec-fetch-site"), secFetchMode: request.headers.get("sec-fetch-mode") }) }) ); return fetch(request); } } ``` ## Verify Installation ### Check Tracker 1. Open your website 2. Open browser DevTools → Network tab 3. Look for requests to `/api/tracker` ### Check Bot Tracking 1. Visit your site with a bot-like user agent 2. Check Dashboard → Bots page 3. You should see the crawl logged ## Three-Layer Architecture Overview CiteFlow uses a three-layer database architecture: | Layer | Purpose | Retention | |-------|---------|-----------| | **Raw** | Debugging raw crawler requests | 30 days | | **Analytics** | Business facts for reporting | Permanent | | **Aggregation** | Aggregated page statistics | Permanent | ## Next Steps - [Tracker Guide](./tracker-guide.md) - Advanced tracking options - [Dashboard Guide](./dashboard-guide.md) - Understanding your data - [API Reference](./api-reference.md) - Build custom integrations - [Architecture](./architecture.md) - System design overview ## Troubleshooting ### No data showing? 1. Check tracker script is installed correctly 2. Verify `data-site-id` matches your site 3. Check for ad blockers blocking requests 4. Review browser console for errors ### Bot tracking not working? 1. Verify Cloudflare Worker is deployed 2. Check the worker logs for errors 3. Ensure your site ID is correct ### Database connection issues? 1. Verify DATABASE_URL is correct 2. Check PostgreSQL is running 3. Ensure database credentials are valid --- Need help? Check the [full documentation](./README.md) or open an issue.