# correctroadh/opentickly architecture

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

- Interactive diagram: https://gitdiagram.com/correctroadh/opentickly
- Repository: https://github.com/correctroadh/opentickly

## Overview

OpenTickly is a private-first, self-hostable time-tracking product with a web app and Go backend. The main user workflow is recording and managing time entries, then reviewing time through reports; the product also supports project/task organization, imports and exports, identity and workspace administration, billing, governance, and webhooks. The sampled source confirms parts of the web query layer and update worker. Many backend connections are inferred from the product layout rather than inspected source, so those links are marked dashed and uncited.

Main entry points: [`apps/website/src/shared/query/web-shell.ts`](https://github.com/correctroadh/opentickly/blob/main/apps/website/src/shared/query/web-shell.ts) (Query facade), [`apps/website/src/app/bootstrap.tsx`](https://github.com/correctroadh/opentickly/blob/main/apps/website/src/app/bootstrap.tsx) (Web interface), [`apps/website/src/features/tracking/ConnectedListView.tsx`](https://github.com/correctroadh/opentickly/blob/main/apps/website/src/features/tracking/ConnectedListView.tsx) (Time entry UI), [`apps/backend/internal/tracking/transport/http/public-api/handler_time_entries.go`](https://github.com/correctroadh/opentickly/blob/main/apps/backend/internal/tracking/transport/http/public-api/handler_time_entries.go) (Tracking API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web app"]
  node_webapp["Web interface<br/>[bootstrap.tsx]"]
  node_webshell["Query facade<br/>[web-shell.ts]"]
  node_sessionq["Session queries"]
  node_timeq["Time-entry queries"]
  node_projectq["Project queries"]
  node_workspaceq["Workspace queries"]
  node_orgq["Organization queries"]
end

subgraph group_tracking["Tracking and reports"]
  node_trackui["Time entry UI"]
  node_trackingapi["Tracking API"]
  node_trackingapp["Tracking services"]
  node_reports["Reports<br/>[service.go]"]
end

subgraph group_workspace["Workspace services"]
  node_catalog["Projects and tasks"]
  node_tenant["Tenants and workspaces<br/>[service.go]"]
  node_membership["Membership<br/>[service.go]"]
  node_identity["Identity and SSO<br/>[service.go]"]
end

subgraph group_operations["Integrations and operations"]
  node_billing["Billing<br/>[invoice_service.go]"]
  node_governance["Governance<br/>[service.go]"]
  node_importing["Import and export<br/>[service.go]"]
  node_webhooks["Webhooks<br/>[service.go]"]
  node_postgres[("PostgreSQL")]
  node_updateworker["Update service<br/>[index.ts]"]
end

node_user(("User"))
node_github["GitHub releases"]

node_user -.->|"uses"| node_webapp
node_webapp -.->|"records time"| node_trackui
node_trackui -.->|"requests data"| node_webshell
node_webshell -->|"re-exports"| node_timeq
node_webshell -->|"re-exports"| node_sessionq
node_webshell -->|"re-exports"| node_projectq
node_webshell -->|"re-exports"| node_workspaceq
node_webshell -->|"re-exports"| node_orgq
node_webapp -.->|"uses queries"| node_webshell
node_webshell -.->|"calls API"| node_trackingapi
node_trackingapi -.->|"delegates"| node_trackingapp
node_trackingapp -.->|"reads and writes"| node_postgres
node_user -.->|"organizes work"| node_catalog
node_user -.->|"reviews time"| node_reports
node_user -.->|"moves data"| node_importing
node_user -.->|"signs in"| node_identity
node_tenant -.->|"persists workspace"| node_postgres
node_membership -.->|"persists membership"| node_postgres
node_identity -.->|"persists identity"| node_postgres
node_catalog -.->|"persists catalog"| node_postgres
node_reports -.->|"reads reports"| node_postgres
node_billing -.->|"persists billing"| node_postgres
node_governance -.->|"persists audit"| node_postgres
node_importing -.->|"imports data"| node_postgres
node_webhooks -.->|"persists hooks"| node_postgres
node_updateworker -->|"fetches releases"| node_github

click node_webapp "https://github.com/correctroadh/opentickly/blob/main/apps/website/src/app/bootstrap.tsx"
click node_webshell "https://github.com/correctroadh/opentickly/blob/main/apps/website/src/shared/query/web-shell.ts"
click node_sessionq "https://github.com/correctroadh/opentickly/blob/main/apps/website/src/shared/query/web-shell-session.ts"
click node_timeq "https://github.com/correctroadh/opentickly/blob/main/apps/website/src/shared/query/web-shell-time-entries.ts"
click node_projectq "https://github.com/correctroadh/opentickly/blob/main/apps/website/src/shared/query/web-shell-projects.ts"
click node_workspaceq "https://github.com/correctroadh/opentickly/blob/main/apps/website/src/shared/query/web-shell-workspaces.ts"
click node_orgq "https://github.com/correctroadh/opentickly/blob/main/apps/website/src/shared/query/web-shell-organizations.ts"
click node_trackui "https://github.com/correctroadh/opentickly/blob/main/apps/website/src/features/tracking/ConnectedListView.tsx"
click node_trackingapi "https://github.com/correctroadh/opentickly/blob/main/apps/backend/internal/tracking/transport/http/public-api/handler_time_entries.go"
click node_trackingapp "https://github.com/correctroadh/opentickly/blob/main/apps/backend/internal/tracking/application/service_time_entries.go"
click node_reports "https://github.com/correctroadh/opentickly/blob/main/apps/backend/internal/reports/application/service.go"
click node_catalog "https://github.com/correctroadh/opentickly/blob/main/apps/backend/internal/catalog/application/service_projects.go"
click node_tenant "https://github.com/correctroadh/opentickly/blob/main/apps/backend/internal/tenant/application/service.go"
click node_membership "https://github.com/correctroadh/opentickly/blob/main/apps/backend/internal/membership/application/service.go"
click node_identity "https://github.com/correctroadh/opentickly/blob/main/apps/backend/internal/identity/application/service.go"
click node_billing "https://github.com/correctroadh/opentickly/blob/main/apps/backend/internal/billing/application/invoice_service.go"
click node_governance "https://github.com/correctroadh/opentickly/blob/main/apps/backend/internal/governance/application/service.go"
click node_importing "https://github.com/correctroadh/opentickly/blob/main/apps/backend/internal/importing/application/service.go"
click node_webhooks "https://github.com/correctroadh/opentickly/blob/main/apps/backend/internal/webhooks/application/service.go"
click node_updateworker "https://github.com/correctroadh/opentickly/blob/main/apps/update-worker/src/index.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_webapp,node_webshell,node_sessionq,node_timeq,node_projectq,node_workspaceq,node_orgq,node_user toneBlue
class node_trackui,node_trackingapi,node_trackingapp,node_reports toneAmber
class node_catalog,node_tenant,node_membership,node_identity toneMint
class node_billing,node_governance,node_importing,node_webhooks,node_postgres,node_updateworker toneRose
class node_github toneIndigo
```

## Components

### Web app

- [Web interface](https://github.com/correctroadh/opentickly/blob/main/apps/website/src/app/bootstrap.tsx): `apps/website/src/app/bootstrap.tsx`
- [Query facade](https://github.com/correctroadh/opentickly/blob/main/apps/website/src/shared/query/web-shell.ts): `apps/website/src/shared/query/web-shell.ts`
- [Session queries](https://github.com/correctroadh/opentickly/blob/main/apps/website/src/shared/query/web-shell-session.ts): `apps/website/src/shared/query/web-shell-session.ts`
- [Time-entry queries](https://github.com/correctroadh/opentickly/blob/main/apps/website/src/shared/query/web-shell-time-entries.ts): `apps/website/src/shared/query/web-shell-time-entries.ts`
- [Project queries](https://github.com/correctroadh/opentickly/blob/main/apps/website/src/shared/query/web-shell-projects.ts): `apps/website/src/shared/query/web-shell-projects.ts`
- [Workspace queries](https://github.com/correctroadh/opentickly/blob/main/apps/website/src/shared/query/web-shell-workspaces.ts): `apps/website/src/shared/query/web-shell-workspaces.ts`
- [Organization queries](https://github.com/correctroadh/opentickly/blob/main/apps/website/src/shared/query/web-shell-organizations.ts): `apps/website/src/shared/query/web-shell-organizations.ts`

### Tracking and reports

- [Time entry UI](https://github.com/correctroadh/opentickly/blob/main/apps/website/src/features/tracking/ConnectedListView.tsx): `apps/website/src/features/tracking/ConnectedListView.tsx`
- [Tracking API](https://github.com/correctroadh/opentickly/blob/main/apps/backend/internal/tracking/transport/http/public-api/handler_time_entries.go): `apps/backend/internal/tracking/transport/http/public-api/handler_time_entries.go`
- [Tracking services](https://github.com/correctroadh/opentickly/blob/main/apps/backend/internal/tracking/application/service_time_entries.go): `apps/backend/internal/tracking/application/service_time_entries.go`
- [Reports](https://github.com/correctroadh/opentickly/blob/main/apps/backend/internal/reports/application/service.go): `apps/backend/internal/reports/application/service.go`

### Workspace services

- [Projects and tasks](https://github.com/correctroadh/opentickly/blob/main/apps/backend/internal/catalog/application/service_projects.go): `apps/backend/internal/catalog/application/service_projects.go`
- [Tenants and workspaces](https://github.com/correctroadh/opentickly/blob/main/apps/backend/internal/tenant/application/service.go): `apps/backend/internal/tenant/application/service.go`
- [Membership](https://github.com/correctroadh/opentickly/blob/main/apps/backend/internal/membership/application/service.go): `apps/backend/internal/membership/application/service.go`
- [Identity and SSO](https://github.com/correctroadh/opentickly/blob/main/apps/backend/internal/identity/application/service.go): `apps/backend/internal/identity/application/service.go`

### Integrations and operations

- [Billing](https://github.com/correctroadh/opentickly/blob/main/apps/backend/internal/billing/application/invoice_service.go): `apps/backend/internal/billing/application/invoice_service.go`
- [Governance](https://github.com/correctroadh/opentickly/blob/main/apps/backend/internal/governance/application/service.go): `apps/backend/internal/governance/application/service.go`
- [Import and export](https://github.com/correctroadh/opentickly/blob/main/apps/backend/internal/importing/application/service.go): `apps/backend/internal/importing/application/service.go`
- [Webhooks](https://github.com/correctroadh/opentickly/blob/main/apps/backend/internal/webhooks/application/service.go): `apps/backend/internal/webhooks/application/service.go`
- **PostgreSQL**
- [Update service](https://github.com/correctroadh/opentickly/blob/main/apps/update-worker/src/index.ts): `apps/update-worker/src/index.ts`

### Other components

- **User**
- **GitHub releases**

## Connections

- User → Web interface: uses (evidence: `README.md`)
- Web interface → Time entry UI: records time (evidence: `README.md`)
- Time entry UI → Query facade: requests data
- Query facade → Time-entry queries: re-exports (evidence: `apps/website/src/shared/query/web-shell.ts`)
- Query facade → Session queries: re-exports (evidence: `apps/website/src/shared/query/web-shell.ts`)
- Query facade → Project queries: re-exports (evidence: `apps/website/src/shared/query/web-shell.ts`)
- Query facade → Workspace queries: re-exports (evidence: `apps/website/src/shared/query/web-shell.ts`)
- Query facade → Organization queries: re-exports (evidence: `apps/website/src/shared/query/web-shell.ts`)
- Web interface → Query facade: uses queries
- Query facade → Tracking API: calls API
- Tracking API → Tracking services: delegates
- Tracking services → PostgreSQL: reads and writes
- User → Projects and tasks: organizes work (evidence: `README.md`)
- User → Reports: reviews time (evidence: `README.md`)
- User → Import and export: moves data (evidence: `README.md`)
- User → Identity and SSO: signs in
- Tenants and workspaces → PostgreSQL: persists workspace
- Membership → PostgreSQL: persists membership
- Identity and SSO → PostgreSQL: persists identity
- Projects and tasks → PostgreSQL: persists catalog
- Reports → PostgreSQL: reads reports
- Billing → PostgreSQL: persists billing
- Governance → PostgreSQL: persists audit
- Import and export → PostgreSQL: imports data
- Webhooks → PostgreSQL: persists hooks
- Update service → GitHub releases: fetches releases (evidence: `apps/update-worker/src/index.ts`)
