# hamedmp/cursorlens architecture

> Architecture diagram of the GitHub repository hamedmp/cursorlens, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hamedmp/cursorlens
- Repository: https://github.com/hamedmp/cursorlens

## Overview

##### Project Type and Purpose
- Cursor Lens is an open-source, full-stack web application built with Next.js and React.
- It functions as a proxy between the Cursor IDE and multiple AI providers (OpenAI, Anthropic, etc.), logging all AI-assisted coding requests and exposing an analytics dashboard.

##### Top-Level File Structure and Architectural Indicators
- **Next.js App**:
- src/app – Server and client routes under the App Router.
- src/components – Reusable UI components (shadcn/ui + Tailwind CSS).
- next.config.js / next.config.mjs – Next.js configuration.
- **API / Proxy Layer**:
- src/app/[...openai]/route.ts – Catch-all proxy endpoint for Cursor→AI requests.
- src/app/api/* – RESTful endpoints for configurations, logs, stats.
- **Data Layer**:
- prisma/schema.prisma & prisma/migrations – Database schema and migrations for PostgreSQL.
- src/lib/prisma.ts – Prisma client setup.
- src/lib/db.ts, lib/utils.ts, lib/cost-calculator.ts – DB helpers and business logic (cost estimation, metadata).
- **Scripts & Jobs**:
- scripts/update-log-costs.ts – Scheduled job for back-filling cost metadata.
- prisma/seed.ts – Initial seed script.
- **DevOps / Deployment**:
- Dockerfile & docker-compose.yml – Containerization.
- start.sh – Startup script.
- .env.example – Environmental variables (.env).

##### Core Components
A. Frontend (Next.js + React)
- Pages & UI: src/app/* pages, NavBar, LogsList, Stats page, ConfigurationModal.
- Theme system via theme-provider & theme-toggle.
B. Backend API (Next.js Serverless Routes)
- Proxy endpoint: “[...openai]” route that intercepts and forwards requests to AI providers.
- REST APIs: /configurations, /logs, /stats.
C. Database Layer (PostgreSQL + Prisma ORM)
- Prisma client handling CRUD on configurations, logs, stats, cost_model, metadata.
D. External AI Providers
- OpenAI, Anthropic, Mistral, Cohere, Groq, Ollama.
- Vercel AI SDK integrates with these providers.
E. Auxiliary Services
- ngrok (tunnel for exposing localhost to Cursor).
- Caching layer for Anthropic prompt caching (TTL logic in DB or in-memory).
- Scheduled jobs: update-log-costs cron job.

##### Relationships and Data Flows
- Proxy route ↔ AI providers (forwards requests, receives responses).
- Proxy route → writes to DB (logs request & response metadata).
- Frontend UI → Backend REST APIs → DB (fetch configurations, logs, stats).
- Scripts (update-log-costs) → DB (update cost_model fields).
- Frontend periodically polls /stats endpoint for real-time monitoring.

##### Architectural Patterns and Design Principles
- **Separation of Concerns**: Frontend / API / Data layers are clearly separated within Next.js.
- **Serverless Functions**: Each API route is an isolated handler.
- **ORM Abstraction**: Prisma provides type-safe DB access.
- **Proxy Pattern**: Catch-all route delegates to multiple AI providers with dynamic configuration.
- **Modular UI**: shadcn/ui and Tailwind components promote reuse.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    CursorIDE["Cursor IDE"]:::external
    ngrok["ngrok Tunnel"]:::external
    subgraph "External AI Providers" 
        direction TB
        OpenAI["OpenAI"]:::external
        Anthropic["Anthropic"]:::external
        Mistral["Mistral"]:::external
        Cohere["Cohere"]:::external
        Groq["Groq"]:::external
        Ollama["Ollama"]:::external
    end

    %% Frontend Layer
    subgraph "Browser (Frontend)" 
        direction TB
        subgraph "Next.js Pages & Layout" 
            direction TB
            HomePage["src/app/page.tsx"]:::frontend
            LogsPage["src/app/logs/page.tsx"]:::frontend
            StatsPage["src/app/stats/page.tsx"]:::frontend
            ConfigPage["src/app/configurations/page.tsx"]:::frontend
            Layout["src/app/layout.tsx"]:::frontend
            GlobalsCSS["src/app/globals.css"]:::frontend
        end
        subgraph "UI Components" 
            direction TB
            NavBar["src/components/NavBar.tsx"]:::frontend
            LogsList["src/components/LogsList.tsx"]:::frontend
            LogDetails["src/components/LogDetails.tsx"]:::frontend
            ConfigurationModal["src/components/ConfigurationModal.tsx"]:::frontend
            ThemeProvider["src/components/theme-provider.tsx"]:::frontend
            ThemeToggle["src/components/theme-toggle.tsx"]:::frontend
            UIComponents["src/components/ui/*"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Backend (Next.js Serverless)" 
        direction TB
        subgraph "Proxy Route" 
            ProxyRoute["src/app/[...openai]/route.ts"]:::backend
        end
        subgraph "REST API Endpoints" 
            direction TB
            ConfigRoute["src/app/api/configurations/route.ts"]:::backend
            LogsRoute["src/app/api/logs/route.ts"]:::backend
            LogDetailRoute["src/app/api/logs/[id]/route.ts"]:::backend
            StatsRoute["src/app/api/stats/route.ts"]:::backend
        end
        subgraph "Business Logic & Helpers" 
            direction TB
            Actions["src/app/actions.ts"]:::backend
            PrismaClient["src/lib/prisma.ts"]:::backend
            DBHelpers["src/lib/db.ts"]:::backend
            Utils["src/lib/utils.ts"]:::backend
            CostCalc["src/lib/cost-calculator.ts"]:::backend
            ModelConfig["src/lib/model-config.ts"]:::backend
        end
    end

    %% Database Layer
    subgraph "Database (PostgreSQL + Prisma)" 
        direction TB
        DB["PostgreSQL"]:::database
        Schema["prisma/schema.prisma"]:::database
        Migrations["prisma/migrations/*"]:::database
    end

    %% Background Jobs & Scripts
    subgraph "Jobs & Scripts" 
        direction TB
        Seed["prisma/seed.ts"]:::job
        UpdateCosts["scripts/update-log-costs.ts"]:::job
    end

    %% DevOps / Deployment
    subgraph "DevOps / Deployment" 
        direction TB
        Dockerfile["Dockerfile"]:::infra
        DockerCompose["docker-compose.yml"]:::infra
        StartScript["start.sh"]:::infra
        EnvExample[".env.example"]:::infra
        NextConfigJS["next.config.js"]:::infra
        NextConfigMJS["next.config.mjs"]:::infra
        TailwindConfig["tailwind.config.ts"]:::infra
        PostCSSConfig["postcss.config.mjs"]:::infra
        TSConfig["tsconfig.json"]:::infra
    end

    %% Flows
    CursorIDE -->|tunnel| ngrok -->|requests| ProxyRoute
    ProxyRoute -->|forwards| OpenAI
    ProxyRoute -->|forwards| Anthropic
    ProxyRoute -->|forwards| Mistral
    ProxyRoute -->|forwards| Cohere
    ProxyRoute -->|forwards| Groq
    ProxyRoute -->|forwards| Ollama
    ProxyRoute -->|writes logs| DB
    HomePage -->|calls| ConfigRoute
    HomePage -->|calls| LogsRoute
    HomePage -->|calls| StatsRoute
    HomePage -->|calls| ConfigRoute
    LogsPage -->|calls| LogsRoute
    StatsPage -->|polls| StatsRoute
    ConfigPage -->|uses| ConfigRoute
    ConfigRoute -->|reads/writes| DB
    LogsRoute -->|reads| DB
    LogDetailRoute -->|reads| DB
    StatsRoute -->|aggregates| DB
    Actions -->|uses| DBHelpers
    Actions -->|uses| Utils
    Actions -->|uses| CostCalc
    Actions -->|uses| ModelConfig
    ConfigRoute -->|calls| Actions
    LogsRoute -->|calls| Actions
    LogDetailRoute -->|calls| Actions
    StatsRoute -->|calls| Actions
    Seed -->|initializes| DB
    UpdateCosts -->|updates| DB

    %% Click Events
    click HomePage "https://github.com/hamedmp/cursorlens/blob/main/src/app/page.tsx"
    click LogsPage "https://github.com/hamedmp/cursorlens/blob/main/src/app/logs/page.tsx"
    click StatsPage "https://github.com/hamedmp/cursorlens/blob/main/src/app/stats/page.tsx"
    click ConfigPage "https://github.com/hamedmp/cursorlens/blob/main/src/app/configurations/page.tsx"
    click Layout "https://github.com/hamedmp/cursorlens/blob/main/src/app/layout.tsx"
    click GlobalsCSS "https://github.com/hamedmp/cursorlens/blob/main/src/app/globals.css"
    click NavBar "https://github.com/hamedmp/cursorlens/blob/main/src/components/NavBar.tsx"
    click LogsList "https://github.com/hamedmp/cursorlens/blob/main/src/components/LogsList.tsx"
    click LogDetails "https://github.com/hamedmp/cursorlens/blob/main/src/components/LogDetails.tsx"
    click ConfigurationModal "https://github.com/hamedmp/cursorlens/blob/main/src/components/ConfigurationModal.tsx"
    click ThemeProvider "https://github.com/hamedmp/cursorlens/blob/main/src/components/theme-provider.tsx"
    click ThemeToggle "https://github.com/hamedmp/cursorlens/blob/main/src/components/theme-toggle.tsx"
    click UIComponents "https://github.com/hamedmp/cursorlens/tree/main/src/components/ui/*"
    click ProxyRoute "https://github.com/hamedmp/cursorlens/blob/main/src/app/[...openai]/route.ts"
    click ConfigRoute "https://github.com/hamedmp/cursorlens/blob/main/src/app/api/configurations/route.ts"
    click LogsRoute "https://github.com/hamedmp/cursorlens/blob/main/src/app/api/logs/route.ts"
    click LogDetailRoute "https://github.com/hamedmp/cursorlens/blob/main/src/app/api/logs/[id]/route.ts"
    click StatsRoute "https://github.com/hamedmp/cursorlens/blob/main/src/app/api/stats/route.ts"
    click Actions "https://github.com/hamedmp/cursorlens/blob/main/src/app/actions.ts"
    click PrismaClient "https://github.com/hamedmp/cursorlens/blob/main/src/lib/prisma.ts"
    click DBHelpers "https://github.com/hamedmp/cursorlens/blob/main/src/lib/db.ts"
    click Utils "https://github.com/hamedmp/cursorlens/blob/main/src/lib/utils.ts"
    click CostCalc "https://github.com/hamedmp/cursorlens/blob/main/src/lib/cost-calculator.ts"
    click ModelConfig "https://github.com/hamedmp/cursorlens/blob/main/src/lib/model-config.ts"
    click Schema "https://github.com/hamedmp/cursorlens/blob/main/prisma/schema.prisma"
    click Migrations "https://github.com/hamedmp/cursorlens/tree/main/prisma/migrations/*"
    click Seed "https://github.com/hamedmp/cursorlens/blob/main/prisma/seed.ts"
    click UpdateCosts "https://github.com/hamedmp/cursorlens/blob/main/scripts/update-log-costs.ts"
    click Dockerfile "https://github.com/hamedmp/cursorlens/tree/main/Dockerfile"
    click DockerCompose "https://github.com/hamedmp/cursorlens/blob/main/docker-compose.yml"
    click StartScript "https://github.com/hamedmp/cursorlens/blob/main/start.sh"
    click EnvExample "https://github.com/hamedmp/cursorlens/blob/main/.env.example"
    click NextConfigJS "https://github.com/hamedmp/cursorlens/blob/main/next.config.js"
    click NextConfigMJS "https://github.com/hamedmp/cursorlens/blob/main/next.config.mjs"
    click TailwindConfig "https://github.com/hamedmp/cursorlens/blob/main/tailwind.config.ts"
    click PostCSSConfig "https://github.com/hamedmp/cursorlens/blob/main/postcss.config.mjs"
    click TSConfig "https://github.com/hamedmp/cursorlens/blob/main/tsconfig.json"

    %% Styles
    classDef frontend fill:#B3CDE3,stroke:#6497B1,color:#03396C
    classDef backend fill:#C7E9B4,stroke:#7DCEA0,color:#145A32
    classDef database fill:#F2F3F4,stroke:#BFC9CA,color:#424949
    classDef external fill:#FDEBD0,stroke:#F5B041,color:#7D6608
    classDef job fill:#FEF9E7,stroke:#FAD7A0,color:#7D6608
    classDef infra fill:#E8DAEF,stroke:#D2B4DE,color:#4A235A
```
