How mitskiyu/capyspace works
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: router.go Router & shared middleware · service.go Auth & sessions · handler.go Space handlers · api.ts API client
Components 17
Go API
- API entrypoint
cmd/api/main.go - Router & shared middleware
internal/router/router.go - Auth handlers
internal/auth/handler.go - Auth & sessions · Credentials, passwords, and session lifecycle.
internal/auth/service.go - Auth middleware
internal/auth/middleware.go - Space handlers
internal/space/handler.go - Space service & validation
internal/space/service.go - Space access middleware
internal/space/middleware.go
Data & realtime
- PostgreSQL access · Pool, DB setup, and sqlc-generated queries.
internal/database/db.go - Users & spaces schema
internal/database/migrations/00001_create_users_table.sql - Session cache
internal/cache/session.go - Presence hub · Coordinates persistent participant connections.
internal/presence/hub.go - Presence client
internal/presence/client.go
Next.js client
- App shell
client/src/app/layout.tsx - App & auth pages
client/src/app/page.tsx - Auth UI & state
client/src/components/auth/signin.tsx - API client
client/src/lib/api.ts
Connections 19
- 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