Documentation

README

docs/README.md

Petunia Documentation

Last Updated: December 19, 2025

Quick Navigation

Root-Level Documentation

DocumentPurpose
README.mdProject overview and quick start
CHANGELOG.mdVersion history and release notes
CONTRIBUTING.mdContribution guidelines
TESTING.mdTest structure, patterns, and guidelines

Architecture & System Design

DocumentDescriptionStatus
ARCHITECTURE.mdSystem architecture overviewCurrent
ARCHITECTURE_PLAN.mdArchitecture migration roadmapActive
MULTI_TENANT_MIDDLEWARE.mdMulti-tenancy implementationCurrent
KNOWLEDGE_ARCHITECTURE.mdKnowledge base and AI architectureCurrent

Security & Compliance

DocumentDescriptionStatus
SECURITY_GUIDE.mdSecurity practices and guidelinesCurrent
RLS_POLICIES.mdRow-Level Security policiesCurrent
ACCOUNT_TOKEN_ENCRYPTION.mdToken encryption implementationCurrent
INTERNAL_API_AUTHENTICATION.mdInternal API auth patternsCurrent
auth-patterns.mdAuthentication flow patternsCurrent

Database & Data

DocumentDescriptionStatus
DATABASE_MIGRATIONS.mdMigration procedures and best practicesCurrent
DATABASE_RESILIENCE.mdDatabase reliability patternsCurrent
VIEWING_DATABASE_IN_SUPABASE.mdSupabase database access guideCurrent
lead-pipeline-schema.mdLead pipeline data modelCurrent

API & Integration

DocumentDescriptionStatus
API_INTEGRATION_GUIDE.mdAPI integration patterns + webhooksCurrent
API_VERSIONING.mdAPI versioning strategyCurrent
API_MIGRATION_EXAMPLE.mdResponse helpers migration guideCurrent
WEBHOOK_IDEMPOTENCY.mdIdempotent webhook handlingCurrent
INTEGRATION_MONITORING.mdIntegration health monitoringCurrent
openapi.yamlOpenAPI specificationCurrent
ml-api-openapi.yamlML API specificationCurrent

Voice & Communications

DocumentDescriptionStatus
VOICE_AI_SETUP.mdVoice AI configuration guideCurrent
CALL_RECORDINGS.mdCall recording architectureCurrent
SEQUENCE_LIMITATIONS.mdAutoresponder sequence limitationsCurrent

Operations & Deployment

DocumentDescriptionStatus
PRE_DEPLOYMENT_CHECKLIST.mdDeployment checklistCurrent
BACKGROUND_JOBS.mdBackground job patternsCurrent
GIT_FLOW.mdGit workflow guidelinesCurrent
DEVELOPER_GUIDE.mdDeveloper onboarding guideCurrent

Business & Strategy

DocumentDescriptionStatus
GTM_STRATEGY.mdGo-to-market strategyCurrent
PRICING_MODEL.mdPricing structureCurrent
KNOWN_LIMITATIONS.mdCurrent limitationsCurrent
OWNERS.mdFeature ownership mapTemplate

Testing Documentation

DocumentDescription
e2e-onboarding-playwright.mdE2E onboarding test guide

Subdirectories

/docs/features/ - Feature Documentation

21 detailed feature specification documents covering authentication, billing, voice, messaging, and more.

/docs/next-actions/ - Active Work Items

Actionable items currently in progress. See next-actions/README.md for format.

/docs/archive/ - Historical Documentation

  • deployment-plans/ - Archived implementation specifications (225 task specs)

/docs/contracts/ - Product Contracts

  • Real Customer Beta Contract
  • Real Customer MVP Contract

/docs/env/ - Environment Configuration

Environment variable documentation and setup guides.

/docs/runbooks/ - Operational Runbooks

Incident response and operational procedures.

/docs/security/ - Security Documentation

Detailed security implementation docs.

/docs/QA/ - Quality Assurance

QA processes and test documentation.

/docs/theme/ - Theme Documentation

UI theme and styling documentation.

/docs/mutation-testing/ - Mutation Testing

Mutation testing configuration and reports.


Documentation Standards

File Naming

  • UPPERCASE_WITH_UNDERSCORES.md for primary docs
  • lowercase-with-dashes.md for secondary/utility docs
  • OpenAPI specs use .yaml extension

Status Indicators

  • Current - Up-to-date and accurate
  • Active - Living document, regularly updated
  • Template - Contains placeholder data
  • Archive - Historical reference only

Maintenance

  • Update this index when adding/removing docs
  • Mark documents with last updated date in their headers
  • Move completed task docs to archive/ or delete

  • Test Documentation: See root TESTING.md and /tests/ READMEs
  • Agent Instructions: See /.claude/CLAUDE.md
  • Temporary Files: Use /.tmp/ (gitignored) for one-time reports