Documentation System

This workspace uses Markdown as the source of truth for shared documentation.

Goals

The docs system is intended to satisfy four requirements:

1. source files stay plain and portable
2. navigation is explicit and easy to maintain
3. the docs render inside the web app at /docs
4. the same content can be exported as standalone static HTML

File Structure

docs/
  navigation.json
  index.md
  getting-started/
  architecture/
  backend/
  product/
  clients/
  examples/
  contributing/
  site/                # generated HTML output

The frontend repo also carries a synced fallback copy at logga-frontend/docs so standalone frontend deploys can build the /docs route even when the parent workspace root is not present in the container.

How Navigation Works

docs/navigation.json is the canonical sidebar definition.

Each entry declares:

• slug: the logical route id
• file: the Markdown source file
• label: the navigation label

This keeps ordering explicit and avoids guessing from filesystem order.

Authoring Rules

Frontmatter

Every docs page should include frontmatter like this:

---
title: Page Title
description: One-sentence description for metadata and previews.
summary: Short summary shown in navigation contexts.
audience:
  - engineering
lastUpdated: 2026-04-09
---

Linking

Prefer relative links to other Markdown files:

[System Overview](../architecture/system-overview.md)

The renderer converts those links automatically for both:

• the in-app /docs route
• the exported HTML site

Scope

If a page starts describing more than one system deeply, split it into multiple pages and add them to navigation.

Add A New Page

1. Create the Markdown file in the appropriate subfolder under docs/.
2. Add frontmatter.
3. Add the page to docs/navigation.json.
4. Link to it from at least one related page.
5. Rebuild the static HTML site.

Regenerate The Static HTML Site

From logga-frontend:

npm run docs:build

This writes the generated site to:

docs/site

The docs:build command also refreshes the frontend fallback bundle before generating static HTML.

When To Update Docs

Update docs when any of the following change:

• route names or auth behavior
• data model shape
• product terminology
• onboarding or local setup steps
• dashboard or iOS workflows

Practical Standard

The standard is not “perfect docs.” The standard is:

• accurate enough to trust
• clear enough to hand to another team
• cheap enough to keep current

If a page becomes stale, fix it immediately or leave a note explaining what is out of date.

Related Docs

• Overview
• Repository Map