Lantern

Appearance

Docs Directory Definitions ​

Last Updated: 2026-01-17

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.md - Firestore schema and data modeling
  • 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, infrastructure changes, or environment-specific configurations.

🤖 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:

  • ENVIRONMENT_SETUP.md - Local development environment configuration
  • CHANGELOG_WORKFLOW.md - How to write and manage changelog entries
  • TESTING_STRATEGIES.md - Testing approaches and best practices
  • DEBUGGING.md - Debugging techniques and tools
  • PERFORMANCE_OPTIMIZATION.md - Performance tuning guidelines
  • FEATURE_DEVELOPMENT.md - Step-by-step feature development workflow

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:

  • SECURITY_POLICY.md - Security policies and compliance
  • ENCRYPTION.md - Encryption implementation details
  • ZERO_KNOWLEDGE_PROOF.md - Zero-knowledge architecture
  • INCIDENT_RESPONSE.md - Security incident response procedures
  • AUDIT_LOG.md - Security audit procedures

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:

  • QUICK_START_PILOT.md - 10-minute overview of current phase/strategy
  • PILOT_STRATEGY.md - Detailed execution plan with timelines and financials
  • COFOUNDER_FEEDBACK_POA.md ⭐ - Strategic roadmap (kept current with feedback)
  • FOUNDER_CONTEXT.md - Market positioning and founder narrative
  • BUSINESS.md - Business model and monetization
  • IP_STRATEGY.md - IP protection and competitive moat
  • MERCHANT_INTEGRATION_POA.md - Merchant onboarding strategy
  • MERCHANT_INTEGRATION_SUMMARY.md - Merchant integration status update
  • TEAM_STRUCTURE.md - Organizational structure, roles, and compensation

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

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

📊 economics/ ​

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

Contents:

  • ECONOMICS.md - Cost breakdown, revenue models, margins, unit economics
  • CALCULATOR.md - Financial modeling tools and sensitivity analysis
  • FUND_ALLOCATION.md - Fund allocation framework (Four Pillars, profit sharing)
  • financial-calculators/ - Python scripts and spreadsheet calculators

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.

📝 worklog/ ​

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

📊 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