ankouros/samakia-web repository overview

⁠samakia-web

⁠Overview

Samakia Web is a Next.js 15 App Router application delivering the platform UI. It integrates with the Auth service for identity flows and reads runtime configuration via @samakia-platform/config.

⁠Technology & Stack

• Runtime: Node.js 20 (Alpine)
• Framework: Next.js 15 (App Router)
• Tooling: ESLint, Jest (unit), Playwright (E2E)
• Dockerfile: ops/docker/web.Dockerfile

⁠Purpose

• Serve the public and authenticated web experience under https://samakia.net.
• Drive OIDC auth flows against https://auth.samakia.net.

⁠Configuration

• Env injected at build/start time via @samakia-platform/config and k8s ExternalSecrets.
• Built with next build, started via next start (port 3000).

UI policy:

• Components follow shadcn/ui primitives under web/src/components/ui.
• Toasts via Sonner (web/src/components/ui/sonner.tsx), mounted with <Toaster />.
• Client code uses @samakia-platform/config/public instead of direct process.env.

⁠Ingress and Routes

• Ingress: ops/k8s/base/ingresses/web.yaml maps samakia.net to service web.
• Next server runs with --hostname 0.0.0.0 --port 3000.

⁠High-Level Architecture

flowchart TD
  I[NGINX Ingress: samakia.net] --> W[Next.js Web]
  W --> A[Auth Service]
  W --> AD[Addresses]
  W --> ST[MinIO App]
  subgraph Observability
    L[Logger/Pino]
  end
  W -.-> L
  classDef obs fill:#f5f5f5,stroke:#bbbbbb,color:#333333
  class L obs

⁠Sequence (Auth Callback)

sequenceDiagram
  participant B as Browser
  participant W as Web (Next.js)
  participant A as Auth (OIDC)

  B->>A: GET /auth/authorize
  A-->>B: 302 redirect to callback with code
  B->>W: GET /auth/callback?code=...
  W->>A: POST /auth/token (code exchange)
  A-->>W: tokens
  W-->>B: session established

⁠Tests

• Unit: web Jest tests
• E2E: web-e2e Playwright journeys; CI reports in dist/.playwright/web-e2e.

⁠Deployment

• Kubernetes: ops/k8s/base/deployments/web.yaml, Service + Ingress samakia.net.
• Image: docker.io/<namespace>/samakia-web:<tag>