# mitskiyu/capyspace architecture

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

- Interactive diagram: https://gitdiagram.com/mitskiyu/capyspace
- Repository: https://github.com/mitskiyu/capyspace

## Overview

#### Purpose and entry points
Capyspace is a full-stack application centered on authenticated users and “spaces,” with real-time presence support. The Go API starts at `cmd/api/main.go`; the Next.js client enters through `client/src/app/layout.tsx` and `client/src/app/page.tsx`.

#### API composition and HTTP boundary
`internal/router/router.go` assembles HTTP routes and shared middleware from `internal/router/middleware.go`. Feature packages expose handlers at the API boundary, notably `internal/auth/handler.go` and `internal/space/handler.go`. This separates transport concerns from feature services.

#### Authentication and session lifecycle
The auth subsystem handles signup, signin, signout, credential validation, password processing, and session handling across `internal/auth/service.go`, `internal/auth/session.go`, and `internal/auth/password.go`. Route protection is enforced through `internal/auth/middleware.go`; auth UI and client state live in `client/src/components/auth/signin.tsx`, `client/src/components/auth/signup.tsx`, and `client/src/lib/auth.ts`.

#### Spaces domain and authorization
Spaces are the primary application domain. Requests flow from `internal/space/handler.go` through validation and domain logic in `internal/space/validate.go` and `internal/space/service.go`. `internal/space/middleware.go` forms the feature-specific access boundary, likely loading or authorizing space context before protected operations.

#### Persistence and schema-generated access
PostgreSQL-oriented persistence is centralized in `internal/database/db.go` and `internal/database/pool.go`. Schema migrations establish users and spaces in `internal/database/migrations/00001_create_users_table.sql` and `internal/database/migrations/00002_create_spaces_table.sql`. SQL query definitions under `internal/database/queries/` produce typed access layers such as `internal/database/users.sql.go` and `internal/database/spaces.sql.go`, configured by `sqlc.yaml`.

#### Cache and real-time presence
Session/cache abstractions are isolated in `internal/cache/cache.go` and `internal/cache/session.go`, allowing session storage to remain distinct from auth policy. Presence is a separate real-time subsystem: `internal/presence/hub.go` coordinates connected participants while `internal/presence/client.go` represents client connections. It is an important boundary between ordinary request/response API handling and persistent live connections.

#### Frontend integration and runtime infrastructure
The frontend is a Bun-managed Next.js application (`client/package.json`, `client/next.config.ts`) with App Router pages for auth under `client/src/app/(auth)/`. Browser-to-API communication is centralized in `client/src/lib/api.ts`. Development infrastructure uses Nix (`flake.nix`), live reload configuration (`.air.toml`), environment variables (`.env.example`), and Just tasks; the documented workflow runs the Go server/database separately from `bun dev`.

Main entry points: [`internal/router/router.go`](https://github.com/mitskiyu/capyspace/blob/main/internal/router/router.go) (Router & shared middleware), [`internal/auth/service.go`](https://github.com/mitskiyu/capyspace/blob/main/internal/auth/service.go) (Auth & sessions), [`internal/space/handler.go`](https://github.com/mitskiyu/capyspace/blob/main/internal/space/handler.go) (Space handlers), [`client/src/lib/api.ts`](https://github.com/mitskiyu/capyspace/blob/main/client/src/lib/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Go API"]
  node_api_main["API entrypoint<br/>Go runtime<br/>[main.go]"]
  node_router["Router &amp; shared middleware<br/>HTTP composition<br/>[router.go]"]
  node_auth_handler["Auth handlers<br/>HTTP handlers<br/>[handler.go]"]
  node_auth_service["Auth &amp; sessions<br/>auth service<br/>[service.go]"]
  node_auth_guard["Auth middleware<br/>route guard<br/>[middleware.go]"]
  node_space_handler["Space handlers<br/>HTTP handlers<br/>[handler.go]"]
  node_space_domain["Space service &amp; validation<br/>domain service<br/>[service.go]"]
  node_space_guard["Space access middleware<br/>feature guard<br/>[middleware.go]"]
end

subgraph group_data["Data &amp; realtime"]
  node_database[("PostgreSQL access<br/>database layer<br/>[db.go]")]
  node_schema["Users &amp; spaces schema<br/>SQL migrations"]
  node_cache[("Session cache<br/>cache abstraction<br/>[session.go]")]
  node_presence_hub{{"Presence hub<br/>realtime coordinator<br/>[hub.go]"}}
  node_presence_client["Presence client<br/>live connection<br/>[client.go]"]
end

subgraph group_client["Next.js client"]
  node_client_layout["App shell<br/>Next.js layout<br/>[layout.tsx]"]
  node_client_pages["App &amp; auth pages<br/>App Router pages<br/>[page.tsx]"]
  node_auth_ui["Auth UI &amp; state<br/>client auth<br/>[signin.tsx]"]
  node_api_client["API client<br/>browser API layer<br/>[api.ts]"]
end

node_api_main -->|"starts"| node_router
node_router -->|"auth routes"| node_auth_handler
node_router -->|"protected routes"| node_auth_guard
node_router -->|"space routes"| node_space_handler
node_auth_guard -->|"authenticated context"| node_space_guard
node_auth_handler -->|"auth requests"| node_auth_service
node_auth_service -->|"user access"| node_database
node_auth_service -->|"stores sessions"| node_cache
node_space_handler -->|"access check"| node_space_guard
node_space_guard -->|"authorized operations"| node_space_domain
node_space_handler -->|"validates and executes"| node_space_domain
node_space_domain -->|"space access"| node_database
node_schema -->|"defines tables"| node_database
node_presence_client -->|"persistent connection"| node_presence_hub
node_client_layout -->|"renders"| node_client_pages
node_client_pages -->|"auth flows"| node_auth_ui
node_auth_ui -->|"uses"| node_api_client
node_api_client -->|"HTTP requests"| node_router
node_api_client -->|"live presence"| node_presence_hub

click node_api_main "https://github.com/mitskiyu/capyspace/blob/main/cmd/api/main.go"
click node_router "https://github.com/mitskiyu/capyspace/blob/main/internal/router/router.go"
click node_auth_handler "https://github.com/mitskiyu/capyspace/blob/main/internal/auth/handler.go"
click node_auth_service "https://github.com/mitskiyu/capyspace/blob/main/internal/auth/service.go"
click node_auth_guard "https://github.com/mitskiyu/capyspace/blob/main/internal/auth/middleware.go"
click node_space_handler "https://github.com/mitskiyu/capyspace/blob/main/internal/space/handler.go"
click node_space_domain "https://github.com/mitskiyu/capyspace/blob/main/internal/space/service.go"
click node_space_guard "https://github.com/mitskiyu/capyspace/blob/main/internal/space/middleware.go"
click node_database "https://github.com/mitskiyu/capyspace/blob/main/internal/database/db.go"
click node_schema "https://github.com/mitskiyu/capyspace/blob/main/internal/database/migrations/00001_create_users_table.sql"
click node_cache "https://github.com/mitskiyu/capyspace/blob/main/internal/cache/session.go"
click node_presence_hub "https://github.com/mitskiyu/capyspace/blob/main/internal/presence/hub.go"
click node_presence_client "https://github.com/mitskiyu/capyspace/blob/main/internal/presence/client.go"
click node_client_layout "https://github.com/mitskiyu/capyspace/blob/main/client/src/app/layout.tsx"
click node_client_pages "https://github.com/mitskiyu/capyspace/blob/main/client/src/app/page.tsx"
click node_auth_ui "https://github.com/mitskiyu/capyspace/blob/main/client/src/components/auth/signin.tsx"
click node_api_client "https://github.com/mitskiyu/capyspace/blob/main/client/src/lib/api.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_api_main,node_router,node_auth_handler,node_auth_service,node_auth_guard,node_space_handler,node_space_domain,node_space_guard toneBlue
class node_database,node_schema,node_cache,node_presence_hub,node_presence_client toneAmber
class node_client_layout,node_client_pages,node_auth_ui,node_api_client toneMint
```

## Components

### Go API

- [API entrypoint](https://github.com/mitskiyu/capyspace/blob/main/cmd/api/main.go): Go runtime · `cmd/api/main.go`
- [Router & shared middleware](https://github.com/mitskiyu/capyspace/blob/main/internal/router/router.go): HTTP composition · `internal/router/router.go`
- [Auth handlers](https://github.com/mitskiyu/capyspace/blob/main/internal/auth/handler.go): HTTP handlers · `internal/auth/handler.go`
- [Auth & sessions](https://github.com/mitskiyu/capyspace/blob/main/internal/auth/service.go): auth service · Credentials, passwords, and session lifecycle. · `internal/auth/service.go`
- [Auth middleware](https://github.com/mitskiyu/capyspace/blob/main/internal/auth/middleware.go): route guard · `internal/auth/middleware.go`
- [Space handlers](https://github.com/mitskiyu/capyspace/blob/main/internal/space/handler.go): HTTP handlers · `internal/space/handler.go`
- [Space service & validation](https://github.com/mitskiyu/capyspace/blob/main/internal/space/service.go): domain service · `internal/space/service.go`
- [Space access middleware](https://github.com/mitskiyu/capyspace/blob/main/internal/space/middleware.go): feature guard · `internal/space/middleware.go`

### Data & realtime

- [PostgreSQL access](https://github.com/mitskiyu/capyspace/blob/main/internal/database/db.go): database layer · Pool, DB setup, and sqlc-generated queries. · `internal/database/db.go`
- [Users & spaces schema](https://github.com/mitskiyu/capyspace/blob/main/internal/database/migrations/00001_create_users_table.sql): SQL migrations · `internal/database/migrations/00001_create_users_table.sql`
- [Session cache](https://github.com/mitskiyu/capyspace/blob/main/internal/cache/session.go): cache abstraction · `internal/cache/session.go`
- [Presence hub](https://github.com/mitskiyu/capyspace/blob/main/internal/presence/hub.go): realtime coordinator · Coordinates persistent participant connections. · `internal/presence/hub.go`
- [Presence client](https://github.com/mitskiyu/capyspace/blob/main/internal/presence/client.go): live connection · `internal/presence/client.go`

### Next.js client

- [App shell](https://github.com/mitskiyu/capyspace/blob/main/client/src/app/layout.tsx): Next.js layout · `client/src/app/layout.tsx`
- [App & auth pages](https://github.com/mitskiyu/capyspace/blob/main/client/src/app/page.tsx): App Router pages · `client/src/app/page.tsx`
- [Auth UI & state](https://github.com/mitskiyu/capyspace/blob/main/client/src/components/auth/signin.tsx): client auth · `client/src/components/auth/signin.tsx`
- [API client](https://github.com/mitskiyu/capyspace/blob/main/client/src/lib/api.ts): browser API layer · `client/src/lib/api.ts`

## Connections

- API entrypoint → Router & shared middleware: starts
- Router & shared middleware → Auth handlers: auth routes
- Router & shared middleware → Auth middleware: protected routes
- Router & shared middleware → Space handlers: space routes
- Auth middleware → Space access middleware: authenticated context
- Auth handlers → Auth & sessions: auth requests
- Auth & sessions → PostgreSQL access: user access
- Auth & sessions → Session cache: stores sessions
- Space handlers → Space access middleware: access check
- Space access middleware → Space service & validation: authorized operations
- Space handlers → Space service & validation: validates and executes
- Space service & validation → PostgreSQL access: space access
- Users & spaces schema → PostgreSQL access: defines tables
- Presence client → Presence hub: persistent connection
- App shell → App & auth pages: renders
- App & auth pages → Auth UI & state: auth flows
- Auth UI & state → API client: uses
- API client → Router & shared middleware: HTTP requests
- API client → Presence hub: live presence
