Lantern

Appearance

Docs Directory Definitions ​

Last Updated: 2026-08-09

This file defines the purpose, scope, and contents of each directory in the /docs folder. Use this as a reference guide for understanding where to find specific documentation and where to place new documents.

📋 Root-Level Files ​

Files in the /docs root directory serve as primary navigation and reference points:

FilePurpose
DIRECTORY_DEFINITIONS.mdThis file—explains all docs directories and organization
CHANGELOG.mdProject changelog tracking all changes (dev entries + production releases)
CONTRIBUTING.mdContributor guidelines, coding standards, and workflow expectations
ABOUT.mdProject overview and high-level description
SANDBOX.mdExperimental notes and testing ground for documentation ideas
TODO.mdDocumentation gaps and items to be completed
index.mdVitePress homepage for the documentation site

📁 Main Directories ​

🏗️ architecture/ ​

Purpose: System design, technical architecture, and foundational patterns.

Contents:

  • SCAFFOLD.md - Project tech stack and architecture rationale
  • PWA.md - Progressive Web App implementation details
  • SCREENS_ORGANIZATION.md - How screens and components are structured
  • DATABASE_SCALING.md - Firestore sharding and growth model (note: there is no DATABASE.md; the collection list lives in AGENTS.md and ONBOARDING.md)
  • SECURITY_ARCHITECTURE.md - Security design patterns
  • API_DESIGN.md - Backend API structure and integration points

When to add: Document system design decisions, architecture patterns, or major technical structures.

🚀 deployment/ ​

Purpose: Deployment processes, CI/CD pipelines, and environment setup.

Contents:

  • DEPLOYMENT.md - Production deployment procedures
  • CICD_GUIDE.md - GitHub Actions workflows and automation
  • ENVIRONMENTS.md - Development, staging, and production environment setup
  • FIREBASE_SETUP.md - Firebase project configuration
  • DISASTER_RECOVERY.md - Backup and recovery procedures

When to add: Document deployment procedures, CI/CD, or environment-specific configuration that ships from this repo. A change made BY HAND in a cloud console goes in infrastructure/ instead.

🗂️ infrastructure/ ​

Purpose: The running record of cloud settings changed by hand, because this repo has no infrastructure as code.

Contents:

  • GCP_CHANGES.md - Ledger of every hand change to a Google Cloud project: what, when, why, the exact command, how to reverse it

When to add: You changed an IAM binding, a log sink, a bucket, an alert policy or a quota in a cloud console or with gcloud. It is a LEDGER, not the source of truth, so an entry never replaces reading the live project.

🤖 discord-bot/ ​

Purpose: Discord bot integration documentation and setup.

Contents:

  • BOT_SETUP.md - Installation and configuration
  • COMMANDS.md - Available commands and usage
  • INTEGRATION_GUIDE.md - How the bot integrates with Lantern systems

When to add: Document new bot commands, integrations, or feature changes.

🐙 github/ ​

Purpose: GitHub-specific integrations, automation, and workflows.

Contents:

  • workflows/ - GitHub Actions workflow documentation
    • README.md - Overview of all workflows
    • testing/ - Testing guides for each workflow
      • TESTING_GITHUB_PROJECTS_V2.md
      • TESTING_AI_ISSUE_TRIAGE.md
      • TESTING_API_KEY_SETUP.md
  • ISSUE_TEMPLATES.md - Issue and PR template documentation
  • GITHUB_PROJECTS_V2_TROUBLESHOOTING.md - Troubleshooting automation issues

When to add: Document new GitHub Actions workflows, issue automation, or GitHub integration changes.

📚 guides/ ​

Purpose: Developer guides, how-to documentation, and operational procedures.

Contents: the folder listing IS the inventory; a hand-maintained per-file list here rotted twice (the pre-2026-08-09 version named four files that did not exist), so this map now names only what matters for routing and lets ls docs/engineering/guides/ be authoritative for the rest:

  • onboarding/ - ONBOARDING.md, the single new-contributor page: what Lantern is, prereqs, quick setup via the AI prompt or the full by-hand path, then architecture, workflow, testing, and security as come-back-later reading. GRANTING_LOGINS_AND_ACCESS.md is its POC-side counterpart: every login and grant a new person needs, who runs it, and when. The tick-box copy a newcomer works through is not a doc at all, it is tooling/templates/onboarding-checklist.md, which npm run context:bootstrap writes into their personal context home
  • ENVIRONMENT_SETUP.md - Secrets and backend-work setup (npm run env:bootstrap); NOT needed to run the app. Original provisioning archived in historical/INITIAL_PROJECT_SETUP.md.
  • SCRIPTS_GUIDE.md, PR_WORKFLOW.md, CHANGELOG_WORKFLOW.md - the working-conventions trio (npm scripts, PR flow, changelog)
  • ADMIN_PORTAL_SETUP.md + ADMIN_PAGE_PATTERNS.md - admin portal setup and its page/design patterns
  • Everything else is topic-named (venues, notifications, logging, webhooks, and so on); open the folder.

When to add: Document developer workflows, setup procedures, or how-to guides that don't fit other categories.

📱 mobile/ ​

Purpose: Mobile-specific optimizations, PWA features, and device handling.

Contents:

  • PWA_OFFLINE.md - Offline functionality and service worker details
  • RESPONSIVE_DESIGN.md - Mobile responsiveness patterns
  • DEVICE_TESTING.md - Cross-device testing procedures
  • PERFORMANCE_MOBILE.md - Mobile performance optimization

When to add: Document mobile-specific features, device handling, or mobile performance issues.

🔒 security/ ​

Purpose: Security policies, practices, and incident response.

Contents: the folder listing IS the inventory (the hand-maintained list here named five files that never existed). What matters for routing:

  • SECURITY_ARCHITECTURE.md - the whole security model, including why admin portal auth is a separate system from the app's
  • ZERO_KNOWLEDGE_ENCRYPTION.md + ZERO_KNOWLEDGE_VISUAL_GUIDE.md - the encryption design, in depth and in pictures
  • SECRETS_MANAGEMENT.md - Secret Manager, .env.local, and npm run env:bootstrap
  • SECURITY_REMEDIATION.md - the live remediation tracker; keep it current in the same PR as the fix
  • Everything else is topic-named (pentest program, phone+PIN encryption, history scrub); open the folder.

Not to be confused with top-level docs/security/, which holds the outward-facing and operational policy documents: incident response playbook, runbooks, and the vulnerability disclosure policy. Engineering detail goes here; policy goes there.

When to add: Document security features, vulnerabilities, fixes, or policies.

🧪 testing/ ​

Purpose: Testing strategies, test setups, and QA procedures.

Contents:

  • TESTING_STRATEGY.md - Overall testing approach
  • UNIT_TESTING.md - Unit test setup and examples
  • INTEGRATION_TESTING.md - Integration test procedures
  • E2E_TESTING.md - End-to-end testing with Playwright/Cypress
  • CROSS_BROWSER_TESTING.md - Browser compatibility testing
  • ACCESSIBILITY_TESTING.md - A11y testing procedures

When to add: Document new testing approaches, test setups, or QA procedures.

✨ features/ ​

Purpose: User-facing feature documentation organized by feature domain.

Structure (per feature):

features/{feature-name}/
  ├── QUICK_START.md          # 5-minute overview
  ├── {FEATURE_NAME}.md       # Complete specification
  ├── IMPLEMENTATION.md       # Developer implementation guide (optional)
  ├── TESTING_GUIDE.md        # QA and testing procedures (optional)
  └── assets/                 # Images and diagrams (optional)

Existing features:

  • lantern-hub/ - Lantern Hub feature documentation
  • profile/ - User profile management
  • wave/ - Wave notifications and messaging
  • frens/ - Friends and social features
  • light-lanterns/ - Light Lanterns feature
  • landing/ - Landing page documentation
  • global-flows/ - Cross-feature flow documentation
  • safety/ - Safety and trust features
  • refactor/ - Refactoring projects and architectural changes

When to add: Create a new feature folder whenever implementing a new user-facing feature.

💼 business/ ​

Purpose: Business strategy, market positioning, and commercial decisions.

Core Documents:

  • README.md - Index. Start here. Points to the canonical business plan (external Google Doc) and the current in-repo docs.
  • COMPLEXITY_VS_STAGE.md - Build-sequencing / complexity-vs-stage risk assessment (current)
  • launches/ - The launch plan, one page per stage. README.md is the parent (stage definitions, the sorting test, P-ratings, status, code names); PROTOTYPE.md, ALPHA.md and BETA.md carry the work
  • IP_STRATEGY.md - IP protection and competitive moat
  • COMPETITORS.md - Competitive landscape
  • EVENT_FIRST_GTM.md - Event-first go-to-market playbook
  • MERCHANT_INTEGRATION_POA.md - Merchant onboarding strategy
  • MERCHANT_INTEGRATION_SUMMARY.md - Merchant integration status update
  • TEAM_STRUCTURE.md - Organizational structure, roles, and compensation

The canonical business plan lives in an external Google Doc (see README.md). The January 2026 plan scaffolding (BUSINESS.md, PILOT_STRATEGY.md, FOUNDER_CONTEXT.md, QUICK_START_PILOT.md) has been archived to docs/archive/business-2026-01/.

When to add: Document strategic decisions, business model changes, or market positioning updates.

Rule: Avoid duplicate summaries—update launches/README.md for overviews instead of creating separate docs.

📊 economics/ ​

Purpose: Financial models, unit economics, and pricing analysis.

Contents:

  • CALCULATOR.md - Financial modeling tools and sensitivity analysis
  • FUND_ALLOCATION.md - Fund allocation framework (Four Pillars, profit sharing)
  • AD_PLACEMENT_ECONOMICS.md - Ad rotation/pacing economics and fairness design
  • financial-calculators/ - Interactive financial calculators

ECONOMICS.md has been archived to docs/archive/business-2026-01/ (superseded by the canonical plan). The calculators here now anchor on the $150 flat campaign; the Google Doc remains authoritative for pricing and financials.

When to add: Document financial models, pricing changes, or economic impact analysis.

Lifecycle: Update quarterly during planning cycles or when financial model changes.

🏛️ governance/ ​

Purpose: Organizational structure, employee rights, decision-making, and legal compliance.

Core Documents (heavily cross-linked):

  • GOVERNANCE.md - Overview of governance structure and legal entities
  • GOVERNANCE_QUICK_REFERENCE.md - One-page cheatsheet of key policies
  • FOUNDATIONAL_PHILOSOPHY.md - Philosophical foundation (Four Pillars)
  • IMMUTABLE_RIGHTS.md - Constitutional rights that cannot be voted away
  • EMPLOYEE_RIGHTS_CHARTER.md - Comprehensive rights and benefits
  • SHAREHOLDER_LENDER_FRAMEWORK.md - Funding structure (lenders have zero decision power)
  • DECISION_MAKING_AUTHORITY.md - Authority matrix by role
  • ANTI_GREED_SAFEGUARDS.md - 21+ structural protections against mission drift
  • HIRING_POLICY.md - Interview process and hiring standards
  • CONTRACTOR_PATHWAY.md - Contractor vs. employee classification
  • LEGAL_COMPLIANCE.md - Legal requirements and compliance checklist
  • SECURITY.md - Security incident response procedures

When to add: Document governance changes, policy updates, or legal compliance requirements.

Rule: These documents are heavily cross-linked—always reference related docs and check GOVERNANCE_QUICK_REFERENCE.md first.

🎨 design/ ​

Purpose: Design system, theme documentation, and UI/UX guidelines.

Contents:

  • THEME.md - Color palette, typography, and design tokens
  • COMPONENT_DESIGN.md - Design patterns and component guidelines
  • ACCESSIBILITY.md - Accessibility design standards

When to add: Document design system changes, new design patterns, or theme updates.

📈 audit/ ​

Purpose: Comprehensive audits of code quality, security, architecture, and documentation.

Contents: Dated audit reports

  • AUDIT_YYYY-MM-DD.md - Comprehensive audit snapshots

Lifecycle:

  • Run quarterly or after major refactors
  • Always include date in filename: AUDIT_2026-01-11.md
  • Include file inventory, broken link checks, outdated content flags, and recommendations

When to add: After major code reviews, security assessments, or documentation overhauls.

📦 projects/ ​

Purpose: One folder per piece of work, holding everything about it. This is where NEW work's documents go (operator direction, 2026-08-31); the project-creation skill owns the scaffolding rules.

Contents: docs/projects/<project-name>/

  • README.md - the front door: what it is, its issue, current state (the only mandatory file)
  • planning.md (ordered plan), backlog.md (unsequenced), design.md, implementation.md, testing.md (the manual test plan), logging.md (the worklog) - each appears when the work needs it

Lifecycle:

  • Created when work is named, before it produces any document
  • Lives on as the work's permanent record
  • Legacy locations (worklog/, planning/, engineering/testing/runs/) keep their existing files; new documents do not go there

When to add: Whenever new work is named that will produce a design, a plan, a test plan, or a worklog.

📝 worklog/ ​

Status (2026-08-31): Legacy for new work. New worklogs go in the work's project folder (docs/projects/<project>/logging.md); existing files stay here.

Purpose: Active development progress tracking, implementation notes, and completion summaries.

Naming Convention: {FEATURE_OR_PHASE}_{OUTCOME}.md

  • Example: WAVE_INTEGRATION_COMPLETE.md, BUG_FIXES_ITERATION_2.md

Template (per entry):

markdown
# {Feature/Work} - {Outcome}
**Date:** YYYY-MM-DD
**Status:** ✅ Complete / ⚠️ In Progress / 🚧 Blocked
**Related Feature(s):** [Link to feature docs]

## Problem Statement / Goal
[What was the issue or goal?]

## Solution Overview
[High-level approach]

## Files Changed/Created
- [File](../../path/to/file.js) - Description

## Testing Results
[How was this validated?]

## Next Steps
[What should be done next?]

Lifecycle:

  • Active in sidebar for ~1 month
  • Move to archive/worklog-historical/ for long-term storage
  • Prefix with date for chronological sorting: 2025-06-15_NEW_FEATURE_COMPLETE.md

When to add: For significant completed work (2+ hours), bug fixes, implementation sprints, or pattern-establishing decisions.

🗂️ archive/ ​

Purpose: Historical documentation no longer in active use.

Contents:

  • worklog-historical/ - Older worklog entries (1+ months old)
  • Other archived documentation as needed

When to use: Move documentation here when it's no longer actively referenced but may be useful for historical context.

📸 screenshots/ and mockups/ and wireframes/ ​

Purpose: Visual assets and design mockups.

Contents:

  • UI screenshots and app previews
  • Design mockups and prototypes
  • Wireframes for features and flows

Organization:

  • Group by feature or domain
  • Use descriptive filenames: dashboard-v2-wireframe.png
  • Link from feature documentation

When to add: When documenting visual features or design processes.

📚 storybook/ ​

Purpose: Component library documentation and Storybook guides.

Contents:

  • Component documentation
  • Story examples
  • Component usage guidelines

Related: Storybook runs at npm run storybook

🎯 strategic-planning/ ​

Purpose: Long-term strategy, roadmaps, and planning documents.

Contents:

  • Roadmaps and timelines
  • Strategic planning documents
  • Product vision documents

Related: See COFOUNDER_FEEDBACK_POA.md in business/ for current priorities.

📄 public/ ​

Purpose: Static assets served with documentation site (VitePress).

🔧 .vitepress/ ​

Purpose: VitePress configuration for the documentation site.

Contents:

  • Site configuration
  • Sidebar structure
  • Navigation setup
  • Styling

🔥 fireside/ ​

Purpose: Lore and fun facts. Warm, curious, non-essential material that makes the codebase a nicer place to spend time. Nothing here is load-bearing.

Contents:

  • ORIGINS.md - living log of where names come from (tools, cryptography, and our own codebase terms)
  • README.md - what the folder is for and how to add to it

When to add: Origin stories, trivia, code easter eggs, or other lore. Keep entries short and accurate; flag anything uncertain rather than letting it harden into repo legend.

📊 Directory Organization Matrix ​

DirectoryAuto-Generated?StructurePurpose
business/OptionalFlatBusiness strategy & positioning
engineering/{subdomain}/✅ YesSubdirectoriesTechnical documentation
features/{name}/✅ YesPer-feature foldersUser-facing features
governance/✅ YesFlatOrganizational & legal
economics/ManualFlatFinancial models
design/ManualFlatDesign system
security/✅ YesFlatSecurity policies
worklog/✅ Yes (recent)FlatDevelopment progress
audit/✅ YesFlatAudit reports

🎓 Key Documentation Guidelines ​

When Creating New Documentation ​

  1. Check DIRECTORY_DEFINITIONS.md first - Use this guide to see if the doc already exists in its proper location
  2. Choose the right directory - Use this guide to find the best fit
  3. Follow naming conventions - Use CAPS_WITH_UNDERSCORES for filenames
  4. Include a date - For worklog and audit files: YYYY-MM-DD_FILENAME.md
  5. Update CHANGELOG.md - Record what you changed
  6. Add cross-references - Link related documentation in a "See Also" section

Anti-Patterns to Avoid ​

❌ Do NOT create:

  • Duplicate files (check existing docs first)
  • Multiple summary files (consolidate into one)
  • Files without dates (in worklog, audit, etc.)
  • Documentation in multiple locations (use one canonical source)

✅ DO:

  • Update existing docs
  • Delete redundant files
  • Link to content instead of duplicating
  • Use clear, user-focused descriptions

Built with VitePress

Copyright © 2026 Lantern