Logga Documentation Overview
Shared documentation for the Logga product, codebase, API surface, and operating model.
Logga is a real-time event tracking product with three main surfaces:
- a TypeScript backend that ingests events and drives sessions, rules, notifications, and reports
- a Next.js dashboard for operators and workspace members
- a native SwiftUI iOS app for the personal, on-device control room experience
This documentation is designed to be:
- modular: each topic lives in its own Markdown file
- reusable: the same source files can be read in raw
.mdform or rendered as HTML - maintainable: navigation is explicit and every page can be updated independently
- shareable: the docs are written for both internal maintainers and adjacent projects
What To Read First
| Goal | Start here |
|---|---|
| Send your first event | Quickstart |
| Have an AI agent wire Logga into your codebase | Add Logga With Your AI Agent |
| Write the integration by hand | Instrumentation Recipes |
| Run the stack locally | Local Development |
| Understand repository ownership | Repository Map |
| Understand how the system fits together | System Overview |
| Learn the domain model | Data Model |
| Use or extend the HTTP API | API Reference |
| Learn how alerts and reports behave | Rules, Reports, and Notifications |
| Learn how project user activity is derived | Project Users Activity |
| Extend the docs themselves | Documentation System |
Core Product Concepts
| Concept | Meaning |
|---|---|
| Workspace | Top-level customer container. Owns environments, projects, API keys, rules, reports, and memberships. |
| Environment | Deployment slice inside a workspace. Current code guarantees at least production and sandbox. |
| Project | Product or app slice inside an environment. Events and sessions are attached to a project. |
| Channel | Named stream inside a project, such as payments, auth, or system. |
| Event | Immutable telemetry record sent by API clients. |
| Session | Multi-step process that can be updated over time and eventually completed, failed, or closed. |
| Rule | Alert definition that evaluates event or absence conditions. |
| Notification | Outbound alert generated from rules. |
| Report | Scheduled aggregate over past events, optionally grouped or filtered. |
Documentation Principles
1. Write for future maintainers
The target reader is someone who did not build the feature last week. Prefer naming things exactly as they exist in code and linking to the relevant docs page instead of hand-waving.
2. Keep pages focused
Do not turn one document into a dumping ground. If a topic grows into its own system, create a dedicated page and add it to docs/navigation.json.
3. Use examples aggressively
Logga is an API-driven product. Examples make docs useful. Prefer real payload shapes, real route names, and real workflow steps.
4. Update docs in the same change window
If a route, model, or workflow changes, update the relevant Markdown page before the context fades. The docs system is intentionally simple so updates are cheap.
Recommended Reading Paths
New engineer onboarding
Product or design context
Integration work
Source Of Truth
These docs intentionally follow the code that exists today:
- backend routes are registered in
logga-backend/src/index.ts - core persistence models live in
logga-backend/prisma/schema.prisma - the dashboard runs from
logga-frontend - the iOS app lives in
logga-app/logga/logga
If you notice drift between docs and code, fix the docs or explicitly note the mismatch in the page that is closest to the source.