# samsraina/kizen architecture

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

- Interactive diagram: https://gitdiagram.com/samsraina/kizen
- Repository: https://github.com/samsraina/kizen

## Overview

Kizen is an issue-tracking and workspace application with a React web client and Go workspace and ticket services backed by shared PostgreSQL access. Users reach the web application through public and authenticated routes; documented capabilities include browsing workspaces, viewing project boards and tickets, and account authentication. On the backend, requests pass through handlers and services to repositories and database queries. The README describes a different target modular-monolith layout than the supplied tree, so this map follows the implementation shown; unsampled frontend-to-API wiring is not asserted.

Main entry points: [`services/workspace/cmd/main.go`](https://github.com/samsraina/kizen/blob/developement/services/workspace/cmd/main.go) (Workspace HTTP), [`internal/database`](https://github.com/samsraina/kizen/tree/developement/internal/database) (Database queries), [`services/ticket/cmd/main.go`](https://github.com/samsraina/kizen/blob/developement/services/ticket/cmd/main.go) (Ticket HTTP), [`web/server.ts`](https://github.com/samsraina/kizen/blob/developement/web/server.ts) (Web server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webserver["Web server<br/>[server.ts]"]
  node_router["Route router<br/>[router.tsx]"]
  node_routes["User routes"]
  node_workspaceui["Workspace UI"]
  node_api_client["API client<br/>[api-client.ts]"]
  node_auth["Authentication<br/>[auth.ts]"]
end

subgraph group_workspace["Workspace service"]
  node_workspace_entry["Workspace HTTP<br/>[main.go]"]
  node_workspace_handler["Workspace handler<br/>[handler.go]"]
  node_workspace_service["Workspace service<br/>[service.go]"]
  node_workspace_domain["Workspace domain<br/>[types.go]"]
  node_workspace_repo["Workspace repository<br/>[repository.go]"]
end

subgraph group_ticket["Ticket service"]
  node_ticket_entry["Ticket HTTP<br/>[main.go]"]
  node_ticket_handler["Ticket handler<br/>[handler.go]"]
  node_ticket_service["Ticket service<br/>[service.go]"]
  node_ticket_domain["Ticket domain<br/>[ticket.go]"]
  node_ticket_repo["Ticket repository<br/>[postgres.go]"]
end

subgraph group_shared["Shared platform"]
  node_database["Database queries"]
  node_postgres[("PostgreSQL")]
  node_middleware["HTTP middleware<br/>[auth.go]"]
end

node_user(("User"))
node_auth_actor(("Auth provider"))

node_user -->|"requests pages"| node_webserver
node_webserver -.->|"serves application"| node_router
node_router -->|"loads routes"| node_routes
node_user -.->|"uses board"| node_workspaceui
node_workspace_entry -->|"registers handler"| node_workspace_handler
node_workspace_handler -->|"calls"| node_workspace_service
node_workspace_service -->|"calls"| node_workspace_repo
node_workspace_repo -->|"queries"| node_database
node_database -.->|"reads and writes"| node_postgres
node_ticket_entry -->|"registers routes"| node_ticket_handler
node_ticket_handler -->|"calls"| node_ticket_service
node_ticket_service -->|"calls"| node_ticket_repo
node_ticket_repo -->|"uses queries"| node_database
node_workspace_entry -->|"installs"| node_middleware
node_ticket_entry -->|"installs"| node_middleware
node_user -.->|"signs in"| node_auth
node_auth -.->|"authenticates"| node_auth_actor
node_workspaceui -.->|"requests data"| node_api_client
node_api_client -.->|"calls service API"| node_workspace_entry

click node_webserver "https://github.com/samsraina/kizen/blob/developement/web/server.ts"
click node_router "https://github.com/samsraina/kizen/blob/developement/web/src/router.tsx"
click node_routes "https://github.com/samsraina/kizen/tree/developement/web/src/routes"
click node_workspaceui "https://github.com/samsraina/kizen/tree/developement/web/src/components/workspaces/interactions"
click node_api_client "https://github.com/samsraina/kizen/blob/developement/web/src/lib/api-client.ts"
click node_auth "https://github.com/samsraina/kizen/blob/developement/web/src/lib/auth.ts"
click node_workspace_entry "https://github.com/samsraina/kizen/blob/developement/services/workspace/cmd/main.go"
click node_workspace_handler "https://github.com/samsraina/kizen/blob/developement/services/workspace/internal/handler/handler.go"
click node_workspace_service "https://github.com/samsraina/kizen/blob/developement/services/workspace/internal/service/service.go"
click node_workspace_domain "https://github.com/samsraina/kizen/blob/developement/services/workspace/internal/domain/types.go"
click node_workspace_repo "https://github.com/samsraina/kizen/blob/developement/services/workspace/internal/infrastructure/repository/repository.go"
click node_ticket_entry "https://github.com/samsraina/kizen/blob/developement/services/ticket/cmd/main.go"
click node_ticket_handler "https://github.com/samsraina/kizen/blob/developement/services/ticket/internal/handler/handler.go"
click node_ticket_service "https://github.com/samsraina/kizen/blob/developement/services/ticket/internal/service/service.go"
click node_ticket_domain "https://github.com/samsraina/kizen/blob/developement/services/ticket/internal/domain/ticket.go"
click node_ticket_repo "https://github.com/samsraina/kizen/blob/developement/services/ticket/internal/infrastructure/repository/postgres.go"
click node_database "https://github.com/samsraina/kizen/tree/developement/internal/database"
click node_middleware "https://github.com/samsraina/kizen/blob/developement/internal/middleware/auth.go"

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_webserver,node_router,node_routes,node_workspaceui,node_api_client,node_auth,node_user toneBlue
class node_workspace_entry,node_workspace_handler,node_workspace_service,node_workspace_domain,node_workspace_repo toneAmber
class node_ticket_entry,node_ticket_handler,node_ticket_service,node_ticket_domain,node_ticket_repo toneMint
class node_database,node_postgres,node_middleware toneRose
class node_auth_actor toneIndigo
```

## Components

### Web application

- [Web server](https://github.com/samsraina/kizen/blob/developement/web/server.ts): `web/server.ts`
- [Route router](https://github.com/samsraina/kizen/blob/developement/web/src/router.tsx): `web/src/router.tsx`
- [User routes](https://github.com/samsraina/kizen/tree/developement/web/src/routes): `web/src/routes`
- [Workspace UI](https://github.com/samsraina/kizen/tree/developement/web/src/components/workspaces/interactions): `web/src/components/workspaces/interactions`
- [API client](https://github.com/samsraina/kizen/blob/developement/web/src/lib/api-client.ts): `web/src/lib/api-client.ts`
- [Authentication](https://github.com/samsraina/kizen/blob/developement/web/src/lib/auth.ts): `web/src/lib/auth.ts`

### Workspace service

- [Workspace HTTP](https://github.com/samsraina/kizen/blob/developement/services/workspace/cmd/main.go): `services/workspace/cmd/main.go`
- [Workspace handler](https://github.com/samsraina/kizen/blob/developement/services/workspace/internal/handler/handler.go): `services/workspace/internal/handler/handler.go`
- [Workspace service](https://github.com/samsraina/kizen/blob/developement/services/workspace/internal/service/service.go): `services/workspace/internal/service/service.go`
- [Workspace domain](https://github.com/samsraina/kizen/blob/developement/services/workspace/internal/domain/types.go): `services/workspace/internal/domain/types.go`
- [Workspace repository](https://github.com/samsraina/kizen/blob/developement/services/workspace/internal/infrastructure/repository/repository.go): `services/workspace/internal/infrastructure/repository/repository.go`

### Ticket service

- [Ticket HTTP](https://github.com/samsraina/kizen/blob/developement/services/ticket/cmd/main.go): `services/ticket/cmd/main.go`
- [Ticket handler](https://github.com/samsraina/kizen/blob/developement/services/ticket/internal/handler/handler.go): `services/ticket/internal/handler/handler.go`
- [Ticket service](https://github.com/samsraina/kizen/blob/developement/services/ticket/internal/service/service.go): `services/ticket/internal/service/service.go`
- [Ticket domain](https://github.com/samsraina/kizen/blob/developement/services/ticket/internal/domain/ticket.go): `services/ticket/internal/domain/ticket.go`
- [Ticket repository](https://github.com/samsraina/kizen/blob/developement/services/ticket/internal/infrastructure/repository/postgres.go): `services/ticket/internal/infrastructure/repository/postgres.go`

### Shared platform

- [Database queries](https://github.com/samsraina/kizen/tree/developement/internal/database): `internal/database`
- **PostgreSQL**
- [HTTP middleware](https://github.com/samsraina/kizen/blob/developement/internal/middleware/auth.go): `internal/middleware/auth.go`

### Other components

- **User**
- **Auth provider**

## Connections

- User → Web server: requests pages (evidence: `web/server.ts`)
- Web server → Route router: serves application
- Route router → User routes: loads routes (evidence: `web/src/router.tsx`)
- User → Workspace UI: uses board
- Workspace HTTP → Workspace handler: registers handler (evidence: `services/workspace/cmd/main.go`)
- Workspace handler → Workspace service: calls (evidence: `services/workspace/internal/handler/handler.go`)
- Workspace service → Workspace repository: calls (evidence: `services/workspace/internal/service/service.go`)
- Workspace repository → Database queries: queries (evidence: `services/workspace/internal/infrastructure/repository/repository.go`)
- Database queries → PostgreSQL: reads and writes
- Ticket HTTP → Ticket handler: registers routes (evidence: `services/ticket/cmd/main.go`)
- Ticket handler → Ticket service: calls (evidence: `services/ticket/internal/handler/handler.go`)
- Ticket service → Ticket repository: calls (evidence: `services/ticket/internal/service/service.go`)
- Ticket repository → Database queries: uses queries (evidence: `services/ticket/internal/infrastructure/repository/postgres.go`)
- Workspace HTTP → HTTP middleware: installs (evidence: `services/workspace/cmd/main.go`)
- Ticket HTTP → HTTP middleware: installs (evidence: `services/ticket/cmd/main.go`)
- User → Authentication: signs in
- Authentication → Auth provider: authenticates
- Workspace UI → API client: requests data
- API client → Workspace HTTP: calls service API