# swetrix/swetrix-api architecture

> Architecture diagram of the GitHub repository swetrix/swetrix-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/swetrix/swetrix-api
- Repository: https://github.com/swetrix/swetrix-api

## Overview

Swetrix is a privacy-first web analytics platform with Cloud and Community editions. Its principal workflow is visitor tracking followed by analytics ingestion and dashboard queries; the README also documents sessions, funnels, errors, performance, replay, and product-management capabilities. Source excerpts establish several service dependencies, but not the full ingestion or web-client wiring, so those links are omitted or marked unverified.

Main entry points: [`backend/apps/cloud/src/project/project.controller.ts`](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/project/project.controller.ts) (Project API), [`backend/apps/cloud/src/analytics/analytics.service.ts`](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/analytics/analytics.service.ts) (Analytics queries), [`backend/apps/cloud/src/auth/auth.service.ts`](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/auth/auth.service.ts) (Authentication), [`backend/apps/cloud/src/mailer/mailer.service.ts`](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/mailer/mailer.service.ts) (Email delivery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tracking["Tracking and analytics"]
  node_tracker["JavaScript tracker<br/>[Lib.ts]"]
  node_analytics_api["Analytics API"]
  node_analytics["Analytics queries"]
  node_bot_detection["Bot detection"]
  node_replays["Session replays"]
end

subgraph group_projects["Projects and insights"]
  node_project_api["Project API"]
  node_project_service["Project management<br/>[project.service.ts]"]
  node_project_entity[("Project records<br/>[project.entity.ts]")]
  node_project_shares[("Project sharing")]
  node_goal[("Goals<br/>[goal.entity.ts]")]
end

subgraph group_accounts["Accounts and access"]
  node_user_service["User accounts<br/>[user.service.ts]"]
  node_user_entity[("User records<br/>[user.entity.ts]")]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_action_tokens["Action tokens"]
  node_action_entity[("Token records")]
  node_mailer["Email delivery<br/>[mailer.service.ts]"]
  node_letter["Email templates<br/>[letter.ts]"]
end

subgraph group_product["Product capabilities"]
  node_alerts["Alerts and notifications<br/>[alert.service.ts]"]
  node_flags["Feature flags"]
  node_experiments["A/B experiments"]
  node_revenue["Revenue analytics<br/>[revenue.service.ts]"]
  node_ai["Ask AI<br/>[ai.service.ts]"]
end

subgraph group_platform["Shared infrastructure"]
  node_clickhouse[("ClickHouse<br/>[clickhouse.ts]")]
  node_logger["Application logging<br/>[logger.service.ts]"]
end

node_visitor(("Site visitor"))

node_visitor -.->|"uses"| node_tracker
node_tracker -.->|"sends events"| node_analytics_api
node_analytics_api -.->|"queries"| node_analytics
node_analytics -->|"checks bots"| node_bot_detection
node_analytics -->|"queries"| node_clickhouse
node_project_api -->|"manages projects"| node_project_service
node_project_api -->|"requests analytics"| node_analytics
node_project_api -->|"checks accounts"| node_user_service
node_project_api -->|"creates tokens"| node_action_tokens
node_project_api -->|"sends email"| node_mailer
node_project_service -->|"reads usage"| node_clickhouse
node_auth -->|"manages users"| node_user_service
node_auth -->|"uses tokens"| node_action_tokens
node_auth -->|"sends email"| node_mailer
node_user_service -->|"persists users"| node_user_entity
node_auth -->|"accesses projects"| node_project_service
node_action_tokens -.->|"stores tokens"| node_action_entity
node_mailer -.->|"uses templates"| node_letter
node_replays -.->|"exports replay data"| node_clickhouse
node_alerts -.->|"notifies by email"| node_mailer
node_experiments -.->|"uses metrics"| node_analytics
node_flags -.->|"supports testing"| node_experiments

click node_tracker "https://github.com/swetrix/swetrix-api/blob/main/packages/tracker-js/src/Lib.ts"
click node_analytics_api "https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/analytics/analytics.controller.ts"
click node_analytics "https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/analytics/analytics.service.ts"
click node_bot_detection "https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/analytics/bot-detection.service.ts"
click node_clickhouse "https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/common/integrations/clickhouse.ts"
click node_project_api "https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/project/project.controller.ts"
click node_project_service "https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/project/project.service.ts"
click node_project_entity "https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/project/entity/project.entity.ts"
click node_project_shares "https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/project/entity/project-share.entity.ts"
click node_goal "https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/goal/entity/goal.entity.ts"
click node_user_service "https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/user/user.service.ts"
click node_user_entity "https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/user/entities/user.entity.ts"
click node_auth "https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/auth/auth.service.ts"
click node_action_tokens "https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/action-tokens/action-tokens.service.ts"
click node_action_entity "https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/action-tokens/action-token.entity.ts"
click node_mailer "https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/mailer/mailer.service.ts"
click node_letter "https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/mailer/letter.ts"
click node_replays "https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/analytics/session-replay-export.service.ts"
click node_alerts "https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/alert/alert.service.ts"
click node_flags "https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/feature-flag/feature-flag.service.ts"
click node_experiments "https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/experiment/experiment.service.ts"
click node_revenue "https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/revenue/revenue.service.ts"
click node_ai "https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/ai/ai.service.ts"
click node_logger "https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/logger/logger.service.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tracker,node_analytics_api,node_analytics,node_bot_detection,node_replays toneBlue
class node_project_api,node_project_service,node_project_entity,node_project_shares,node_goal toneAmber
class node_user_service,node_user_entity,node_auth,node_action_tokens,node_action_entity,node_mailer,node_letter toneMint
class node_alerts,node_flags,node_experiments,node_revenue,node_ai toneRose
class node_clickhouse,node_logger,node_visitor toneIndigo
```

## Components

### Tracking and analytics

- [JavaScript tracker](https://github.com/swetrix/swetrix-api/blob/main/packages/tracker-js/src/Lib.ts): `packages/tracker-js/src/Lib.ts`
- [Analytics API](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/analytics/analytics.controller.ts): `backend/apps/cloud/src/analytics/analytics.controller.ts`
- [Analytics queries](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/analytics/analytics.service.ts): `backend/apps/cloud/src/analytics/analytics.service.ts`
- [Bot detection](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/analytics/bot-detection.service.ts): `backend/apps/cloud/src/analytics/bot-detection.service.ts`
- [Session replays](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/analytics/session-replay-export.service.ts): `backend/apps/cloud/src/analytics/session-replay-export.service.ts`

### Projects and insights

- [Project API](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/project/project.controller.ts): `backend/apps/cloud/src/project/project.controller.ts`
- [Project management](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/project/project.service.ts): `backend/apps/cloud/src/project/project.service.ts`
- [Project records](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/project/entity/project.entity.ts): `backend/apps/cloud/src/project/entity/project.entity.ts`
- [Project sharing](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/project/entity/project-share.entity.ts): `backend/apps/cloud/src/project/entity/project-share.entity.ts`
- [Goals](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/goal/entity/goal.entity.ts): `backend/apps/cloud/src/goal/entity/goal.entity.ts`

### Accounts and access

- [User accounts](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/user/user.service.ts): `backend/apps/cloud/src/user/user.service.ts`
- [User records](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/user/entities/user.entity.ts): `backend/apps/cloud/src/user/entities/user.entity.ts`
- [Authentication](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/auth/auth.service.ts): `backend/apps/cloud/src/auth/auth.service.ts`
- [Action tokens](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/action-tokens/action-tokens.service.ts): `backend/apps/cloud/src/action-tokens/action-tokens.service.ts`
- [Token records](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/action-tokens/action-token.entity.ts): `backend/apps/cloud/src/action-tokens/action-token.entity.ts`
- [Email delivery](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/mailer/mailer.service.ts): `backend/apps/cloud/src/mailer/mailer.service.ts`
- [Email templates](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/mailer/letter.ts): `backend/apps/cloud/src/mailer/letter.ts`

### Product capabilities

- [Alerts and notifications](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/alert/alert.service.ts): `backend/apps/cloud/src/alert/alert.service.ts`
- [Feature flags](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/feature-flag/feature-flag.service.ts): `backend/apps/cloud/src/feature-flag/feature-flag.service.ts`
- [A/B experiments](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/experiment/experiment.service.ts): `backend/apps/cloud/src/experiment/experiment.service.ts`
- [Revenue analytics](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/revenue/revenue.service.ts): `backend/apps/cloud/src/revenue/revenue.service.ts`
- [Ask AI](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/ai/ai.service.ts): `backend/apps/cloud/src/ai/ai.service.ts`

### Shared infrastructure

- [ClickHouse](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/common/integrations/clickhouse.ts): `backend/apps/cloud/src/common/integrations/clickhouse.ts`
- [Application logging](https://github.com/swetrix/swetrix-api/blob/main/backend/apps/cloud/src/logger/logger.service.ts): `backend/apps/cloud/src/logger/logger.service.ts`

### Other components

- **Site visitor**

## Connections

- Site visitor → JavaScript tracker: uses
- JavaScript tracker → Analytics API: sends events
- Analytics API → Analytics queries: queries
- Analytics queries → Bot detection: checks bots (evidence: `backend/apps/cloud/src/analytics/analytics.service.ts`)
- Analytics queries → ClickHouse: queries (evidence: `backend/apps/cloud/src/analytics/analytics.service.ts`)
- Project API → Project management: manages projects (evidence: `backend/apps/cloud/src/project/project.controller.ts`)
- Project API → Analytics queries: requests analytics (evidence: `backend/apps/cloud/src/project/project.controller.ts`)
- Project API → User accounts: checks accounts (evidence: `backend/apps/cloud/src/project/project.controller.ts`)
- Project API → Action tokens: creates tokens (evidence: `backend/apps/cloud/src/project/project.controller.ts`)
- Project API → Email delivery: sends email (evidence: `backend/apps/cloud/src/project/project.controller.ts`)
- Project management → ClickHouse: reads usage (evidence: `backend/apps/cloud/src/project/project.service.ts`)
- Authentication → User accounts: manages users (evidence: `backend/apps/cloud/src/auth/auth.service.ts`)
- Authentication → Action tokens: uses tokens (evidence: `backend/apps/cloud/src/auth/auth.service.ts`)
- Authentication → Email delivery: sends email (evidence: `backend/apps/cloud/src/auth/auth.service.ts`)
- User accounts → User records: persists users (evidence: `backend/apps/cloud/src/user/user.service.ts`)
- Authentication → Project management: accesses projects (evidence: `backend/apps/cloud/src/auth/auth.service.ts`)
- Action tokens → Token records: stores tokens (evidence: `backend/apps/cloud/src/action-tokens/action-tokens.service.ts`)
- Email delivery → Email templates: uses templates
- Session replays → ClickHouse: exports replay data
- Alerts and notifications → Email delivery: notifies by email
- A/B experiments → Analytics queries: uses metrics
- Feature flags → A/B experiments: supports testing
