getcito-worlds-first-open-source-aio-aeo-or-geo-tool

Open source AI visibility tracking and optimization — self-hosted.

Learn more »

• About
• Features
• Demo
• Tech Stack
• Architecture Overview
• Project Structure
• Prerequisites
• Installation
  • Option A — Docker Compose (recommended)
  • Option B — Local development
• Configuration
• Usage
• Available Scripts
• API Documentation
• Database
• Deployment Documentation
  • 1. Local Deployment
  • 2. Demo Deployment
  • 3. White Label Deployment
• Testing
• Linting & Formatting
• CI/CD
• Security Notes
• Contributing
• Roadmap
• License
• Acknowledgements
• Contact

Getcito is an open-source, self-hosted platform for tracking and optimizing your AI visibility — also known as:

• AEO — Answer Engine Optimization
• GEO — Generative Engine Optimization
• LLMO — LLM Optimization

Getcito tracks how AI answer engines (ChatGPT, Google AI Mode, Perplexity, Gemini, Copilot, Grok, and others) mention, cite, and describe your brand — so you can benchmark competitors and grow your presence in AI answers. Run it on your own infrastructure, own your data, and audit exactly how every metric is calculated.

It is a free alternative to hosted tools like Profound, Peec, and Otterly.

• 📊 Prompt tracking — schedule prompts and record how AI engines answer them over time.
• 🔎 Citation & mention analysis — extract which brands, domains, and sources each AI response cites.
• 🏷️ Brand & competitor benchmarking — track your brand alongside competitors on the same prompts.
• 🤖 Multiple AI surfaces — ChatGPT, Google AI Mode, Google AI Overview, Perplexity, Gemini, Copilot, Grok.
• 🔌 Pluggable scrapers & LLM providers — BrightData, Oxylabs, Olostep, Cloro, and DataForSEO for scraping; OpenRouter, Anthropic, OpenAI, Mistral, and Azure AI Foundry for direct LLM calls.
• 📄 Reports — background report generation over collected data.
• ⚙️ Background job engine — durable scheduling and retries via pg-boss on PostgreSQL.
• 🚦 Admin operations — inspect and reprioritize the prompt queue, review provider usage and latency, and safely delete brands.
• 📅 Flexible reporting — share custom date ranges and compare range-average visibility with the latest result.
• 🔑 REST API — Bearer-authenticated /api/v1 for brands, competitors, prompts, and reports.
• 🎨 White-label mode — rebrandable deployment with Auth0 SSO.

Try the live demo at demo.getcito.com to see prompt tracking and citation analysis in action.

Getcito is a pnpm/Turborepo monorepo of two apps backed by shared packages. The web app serves the dashboard and REST API; the worker runs scheduled scraping, analysis, and report jobs off a pg-boss queue in PostgreSQL. Scraper and LLM providers are called by the worker to collect AI answers.

flowchart LR
    User([User / Browser]) -->|HTTP| Web[apps/web<br/>TanStack Start dashboard + /api/v1]
    Web -->|read/write| DB[(PostgreSQL<br/>Drizzle schema)]
    Web -->|enqueue jobs| DB
    Worker[apps/worker<br/>pg-boss jobs] -->|poll queues| DB
    Worker -->|scrape AI answers| Scrapers[BrightData / Oxylabs<br/>Olostep / DataForSEO]
    Worker -->|direct LLM calls| LLM[OpenRouter / Anthropic<br/>OpenAI / Mistral]

Prompt tracking lifecycle:

sequenceDiagram
    participant Sched as schedule-maintenance (cron */5)
    participant Q as pg-boss queue
    participant W as process-prompt job
    participant P as Scraper / LLM provider
    participant DB as PostgreSQL

    Sched->>Q: enqueue due prompts
    Q->>W: dispatch process-prompt
    W->>P: run prompt on AI surface
    P-->>W: answer + citations
    W->>DB: persist snapshot & metrics

Worker queues (from apps/worker/src): process-prompt, generate-report, analyze-brand, schedule-maintenance (cron */5 * * * *), and sync-auth0-memberships (white-label only, */15 * * * *).

getcito/
├── apps/
│   ├── web/          # TanStack Start dashboard + /api/v1 (Vite dev :3000, Nitro build)
│   └── worker/       # pg-boss background jobs (tsx runtime)
├── packages/
│   ├── api-spec/     # OpenAPI 3 spec (openapi.json)
│   ├── config/       # Env registry/validation, scrape-target parsing, shared constants
│   ├── deployment/   # Deployment-mode wiring (local / demo / whitelabel)
│   ├── lib/          # DB (Drizzle), auth (Better Auth), providers, onboarding, DataForSEO
│   ├── local/        # Local-mode UI/components
│   ├── og/           # Open Graph image rendering (Takumi)
│   ├── ui/           # Design system (Radix + Tailwind)
│   └── whitelabel/   # White-label theming + Auth0 hooks
├── docker/           # Multi-stage Dockerfile + entrypoint
├── e2e/              # Playwright end-to-end tests
├── scripts/          # License check, release notes, version sync
├── docker-compose.yml
├── docker-compose.whitelabel.yml
├── turbo.json
└── pnpm-workspace.yaml

For Docker deployment:

• Docker with Docker Compose

For local development:

• Node.js 24.x (enforced via engines; use nvm use 24)
• pnpm 11.10.0 (corepack enable pnpm)
• PostgreSQL 16 or newer (or run it via Docker, which defaults to 18)

Builds and runs the full stack (PostgreSQL, migrations, web, worker, Adminer) from source.

# Clone
git clone https://github.com/ai-search-guru/getcito-worlds-first-open-source-aio-aeo-or-geo-tool.git
cd getcito-worlds-first-open-source-aio-aeo-or-geo-tool

# Create the environment file and fill in real values (see Configuration)
cp .env.example .env

# Build and start
docker compose build
docker compose up -d

Services exposed on the host:

# Install dependencies
corepack enable pnpm
pnpm install

# Env file is read from the repo root AND apps/web/.env (see Configuration)
# Copy the committed templates, then replace their placeholder values.
cp .env.example .env
cp apps/web/.env.example apps/web/.env

# Run all dev servers via Turborepo
pnpm dev

Dev port: web → http://localhost:3000. The worker loads env from apps/web/.env (via --env-file) and is only needed for background job processing.

Environment variables are the single source of truth. The canonical registry lives in packages/config/src/env-registry.ts; startup validation reports any missing required vars for the active DEPLOYMENT_MODE.

Deployment modes (DEPLOYMENT_MODE): local, demo, whitelabel, cloud. Required-column legend: local = required in local mode · wl = required in white-label mode · scraper = required only when SCRAPE_TARGETS references that provider · optional = never required at startup.

pnpm dev      # start all dev servers (web :3000) via Turborepo
pnpm build    # build all apps/packages for production
pnpm test     # run unit tests (Vitest)
pnpm lint     # lint with Biome
pnpm format   # format with Biome

Production (per app): pnpm build emits a Nitro server bundle for web; start with node .output/server/index.mjs (see the app's start script). The worker runs via tsx src/index.ts.

Root (package.json):

Per app / package (selected):

The web app exposes a REST API under /api/v1. The full contract is defined in packages/api-spec/src/openapi.json (OpenAPI 3).

Authentication: Bearer token — Authorization: Bearer <token>.

Example:

curl -H "Authorization: Bearer $GETCITO_TOKEN" \
     http://localhost:3001/api/v1/brands

• PostgreSQL 16+, accessed via Drizzle ORM (schema in packages/lib/src/db). Docker Compose defaults new installations to PostgreSQL 18.
• Migrations are managed with drizzle-kit. Run from packages/lib:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/getcito \
  npx drizzle-kit migrate

Under Docker Compose, the db-migrate service runs migrations automatically before web and worker start. pg-boss also creates its own queue schema on worker startup.

Getcito supports multiple deployment models via Docker Compose. Below are the comprehensive guides for deploying Getcito locally, as a demo, or as a fully white-labeled instance.

The local deployment builds and runs the full stack (PostgreSQL, automatic migrations, web dashboard, background worker, and Adminer DB UI) from source.

Prerequisites:

• Docker with Docker Compose plugin.
• A clone of this repository.

Step-by-step Setup:

1. Configure Environment Variables Copy the committed template to .env, then fill in your actual values. Ensure DEPLOYMENT_MODE is set to local:

   cp .env.example .env

   Required variables include: DATABASE_URL, DEPLOYMENT_MODE, BETTER_AUTH_SECRET, and any required SCRAPE_TARGETS API keys.

2. Build Docker Images

   docker compose build

3. Start the Stack

   docker compose up -d

What happens at startup:

sequenceDiagram
    participant D as Docker Compose
    participant DB as PostgreSQL
    participant M as db-migrate
    participant W as Web / Worker
    D->>DB: Start Database
    DB-->>D: Healthy (port 5433)
    D->>M: Run Migrations (drizzle-kit)
    M-->>D: Completed
    D->>W: Start Web and Worker

Access URLs:

• Web App: http://localhost:3001
• Adminer (Database UI): http://localhost:8081
• PostgreSQL: localhost:5433 (Username: postgres, Password: postgres, DB: getcito)

Common Commands:

• View logs: docker compose logs -f web
• Stop services: docker compose down
• Rebuild containers: docker compose build --no-cache
• Wipe database volume: docker compose down -v

The Demo deployment mode (DEPLOYMENT_MODE=demo) is designed to host a public or staging instance where users can test the application.

Demo Capabilities Verified in Repo:

• The login screen will automatically read VITE_DEMO_EMAIL and VITE_DEMO_PASSWORD from your environment variables to pre-fill the login form for test users.
• Relies on the same standard infrastructure (PostgreSQL, web, worker).

Setup:

1. Configure your .env file with DEPLOYMENT_MODE=demo and VITE_DEPLOYMENT_MODE=demo.
2. Add your demo credentials:

   VITE_DEMO_EMAIL=team@getcito.com
   VITE_DEMO_PASSWORD=your_demo_password

3. Deploy using the standard Compose commands:

   docker compose build
   docker compose up -d

(Note: External cloud hosting or demo-specific infrastructure is not provided in this repository; it relies solely on the demo mode application flag).

Getcito supports a fully rebrandable White Label mode powered by Auth0 SSO.

White Label Capabilities:

• Custom branding baked into the client bundle at build time: App Name, App Icon, Parent Brand URLs, and Custom Optimization URL Templates.
• Authentication delegated completely to Auth0.
• Includes a Docker Compose file with configurable host ports (Web 3000, DB 5432, Adminer 8080 by default).

Setup:

1. Review the Compose Template The repository includes docker-compose.whitelabel.yml. It contains no secrets; all credentials and branding come from .env.

   Click to view docker-compose.whitelabel.yml template

   services:
     postgres:
       image: postgres:${POSTGRES_IMAGE_TAG:-18-alpine}
       ports:
         - "127.0.0.1:${POSTGRES_PORT:-5432}:5432"
       environment:
         POSTGRES_USER: postgres
         POSTGRES_PASSWORD: postgres
         POSTGRES_DB: getcito
       volumes:
         - postgres_data:/var/lib/postgresql/data
       healthcheck:
         test: ["CMD-SHELL", "pg_isready -U postgres"]
         interval: 5s
         timeout: 5s
         retries: 5
   
     adminer:
       image: adminer
       restart: always
       ports:
         - "${ADMINER_PORT:-8080}:8080"
       environment:
         ADMINER_DEFAULT_SERVER: postgres
         start_period: 30s
   
     db-migrate:
       build:
         context: .
         dockerfile: docker/Dockerfile
         target: migrate
       environment:
         - DATABASE_URL=postgres://postgres:postgres@postgres:5432/getcito
       depends_on:
         postgres:
           condition: service_healthy
   
     web:
       build:
         context: .
         dockerfile: docker/Dockerfile
         target: web
         args:
           DEPLOYMENT_MODE: whitelabel
           VITE_DEPLOYMENT_MODE: whitelabel
           VITE_APP_NAME: ${VITE_APP_NAME}
           VITE_APP_ICON: ${VITE_APP_ICON}
           VITE_APP_URL: ${VITE_APP_URL}
           VITE_APP_PARENT_NAME: ${VITE_APP_PARENT_NAME}
           VITE_APP_PARENT_URL: ${VITE_APP_PARENT_URL}
           VITE_OPTIMIZATION_URL_TEMPLATE: ${VITE_OPTIMIZATION_URL_TEMPLATE}
           VITE_ONBOARDING_REDIRECT_URL_TEMPLATE: ${VITE_ONBOARDING_REDIRECT_URL_TEMPLATE}
           VITE_AUTH0_DOMAIN: ${VITE_AUTH0_DOMAIN}
           VITE_AUTH0_CLIENT_ID: ${VITE_AUTH0_CLIENT_ID}
           VITE_APP_TIMEZONE: ${VITE_APP_TIMEZONE:-}
           VITE_APP_LOCALE: ${VITE_APP_LOCALE:-}
       env_file:
         - .env
       ports:
         - "${WEB_PORT:-3000}:3000"
       depends_on:
         postgres:
           condition: service_healthy
         db-migrate:
           condition: service_completed_successfully
   
     worker:
       build:
         context: .
         dockerfile: docker/Dockerfile
         target: worker
       env_file:
         - .env
       depends_on:
         postgres:
           condition: service_healthy
         db-migrate:
           condition: service_completed_successfully
   
   volumes:
     postgres_data:

2. Configure Environment Variables Copy .env.whitelabel.example to .env, then provide the required Auth0, branding, and provider values. Existing PostgreSQL 16 deployments must keep POSTGRES_IMAGE_TAG=16-alpine until completing a dump/restore migration.

   POSTGRES_IMAGE_TAG=18-alpine
   DEPLOYMENT_MODE=whitelabel
   VITE_DEPLOYMENT_MODE=whitelabel
   AUTH0_CLIENT_ID=your_client_id
   AUTH0_CLIENT_SECRET=your_client_secret
   AUTH0_MGMT_API_DOMAIN=your_mgmt_api_domain
   VITE_APP_NAME="Acme AI Search"
   VITE_APP_ICON="https://cdn.example.com/icon.png"
   VITE_APP_URL="http://localhost:3000"
   VITE_APP_PARENT_NAME="Acme"
   VITE_APP_PARENT_URL="http://localhost:3000"
   VITE_OPTIMIZATION_URL_TEMPLATE="..."
   VITE_APP_TIMEZONE=Asia/Kolkata
   VITE_APP_LOCALE=en-IN

3. Build and Deploy Important: Client variables (VITE_*) are read during the build step and baked into the image.

   docker compose -f docker-compose.whitelabel.yml build
   docker compose -f docker-compose.whitelabel.yml up -d

pnpm test                 # unit tests (Vitest) across the workspace
pnpm --filter @workspace/web test:storybook   # Storybook interaction tests

# End-to-end (Playwright) — requires browsers + a running app
pnpm exec playwright install
pnpm test:e2e             # or: pnpm test:e2e-local

E2E tests live in e2e/ and are separate from unit tests.

Both linting and formatting are handled by Biome (config in biome.json).

pnpm lint      # turbo lint (biome lint per package)
pnpm format    # biome format --write .
pnpm knip      # detect unused files, dependencies, and exports

Releases are managed on master by the GitHub Actions release workflow and Changesets (pnpm changeset → pnpm version-packages → GitHub Release).

• Never commit secrets. API keys, .env contents, and auth secrets must stay out of version control. Generate BETTER_AUTH_SECRET as random hex per deployment.
• Docker runtime images run as non-root users.
• pnpm-workspace.yaml pins security-patched transitive dependency versions (see the overrides block) and enforces a minimum release age / no-downgrade trust policy for new packages.
• Report vulnerabilities privately per SECURITY.md — email team@getcito.com, do not open a public issue.

Contributions are welcome. For minor fixes, open a PR directly; for larger changes, open an issue first. See CONTRIBUTING.md and AGENTS.md.

• Branching / PRs: open PRs from your own fork/account against master.
• Coding standards: TypeScript; format & lint with Biome (pnpm format, pnpm lint); keep changes type-clean (check-types).
• Changesets: add a short, end-user-focused changeset scoped to the affected packages (pnpm changeset).
• CLA: before your first PR merges, add your GitHub username to .github/contributors.txt — see CLA.md.
• Code of Conduct: see CODE_OF_CONDUCT.md.

Tracked on the GitHub Project board and in Issues.

Released under the MIT License.

GetCito v9 is a fork of Elmo, © 2026 Blue Whale Software, LLC, used under the MIT License. Modifications and additions in this repository are © 2026 GetCito. Both copyright notices are retained in LICENSE.md.

Contributions are covered by the Contributor License Agreement.

Based on Elmo and built with TanStack Start, Drizzle ORM, Better Auth, pg-boss, Fumadocs, Biome, and Turborepo, and integrates BrightData, Oxylabs, Olostep, Cloro, DataForSEO, Azure AI Foundry, OpenRouter, Anthropic, OpenAI, and Mistral.

• 📧 team@getcito.com
• 📞 India: +91-96505-10773 · US: +1-623-223-7423