System Overview

Logga is built around one central idea: structured operational activity should be easy to ingest, easy to browse, and easy to turn into native notifications and summaries.

End-To-End Flow

1. A client sends an event or session update to the backend.
2. The backend authenticates the request against a workspace and environment.
3. The backend resolves the project and channel.
4. The backend writes the canonical record to PostgreSQL through Prisma.
5. Rules, notifications, reports, and dashboards read from those persisted records.
6. The web dashboard and iOS app query backend APIs to show current workspace state.

Major Surfaces

Backend API

The backend is the system of record. It exposes:

• auth routes under /auth
• dashboard routes under /v1/dashboard
• event ingest and browsing under /v1/events
• session lifecycle under /v1/sessions
• rules under /v1/rules
• reports under /v1/reports
• device token registration under /v1/device-tokens

It also starts background workers for absence checks and scheduled reports during server startup.

Web Dashboard

The Next.js dashboard is the operator surface. It is where maintainers review workspaces, events, sessions, reports, and project-level activity.

Native iOS App

The SwiftUI app is a more personal control room. It emphasizes native alerts, activity review, project navigation, and report access.

Multi-Tenant Structure

The current domain hierarchy is:

Workspace
  -> Environment
    -> Project
      -> Channel
        -> Event
        -> Session

Rules, notifications, device tokens, and reports hang off the workspace plus environment layer, with optional channel targeting.

Environment Model

The backend guarantees a minimum environment model for each workspace:

• production
• sandbox

These are enforced through ensureWorkspaceEnvironments() in the backend environment helpers. Existing routes generally resolve a workspace plus one environment before returning or mutating data.

Authentication Model

There are two main request identities:

• dashboard user auth for human-operated dashboard flows
• API key auth for server-to-server ingestion

Some routes use hybrid auth, which lets API keys and user sessions reach the same route family when that makes sense. Events, rules, channels, sessions, stats, notifications, and device token routes are wired this way.

Persistence Strategy

PostgreSQL is the primary store, accessed through Prisma. Core characteristics:

• events are immutable records
• sessions are mutable records with a terminal state
• rules and reports are stored as configuration
• notifications are persisted for later inspection
• environment scoping is first-class across most models

See Data Model for the schema-level view.

System Diagram

flowchart LR
    A["Client SDK / API caller"] --> B["Backend API"]
    B --> C["PostgreSQL via Prisma"]
    C --> D["Rules & notifications"]
    C --> E["Scheduled reports"]
    C --> F["Dashboard queries"]
    C --> G["iOS app queries"]
    D --> H["Push delivery / notification history"]

Design Intent

The architecture favors a few practical rules:

• keep ingest simple and explicit
• make scoping obvious through workspace and environment boundaries
• persist enough snapshot data to support product analytics and alert context later
• reuse the same canonical backend for both dashboard and native clients

Related Docs

• Repository Map
• Data Model
• Rules, Reports, and Notifications