Petunia Documentation
Last Updated: December 19, 2025
Quick Navigation
Root-Level Documentation
| Document | Purpose |
|---|---|
| README.md | Project overview and quick start |
| CHANGELOG.md | Version history and release notes |
| CONTRIBUTING.md | Contribution guidelines |
| TESTING.md | Test structure, patterns, and guidelines |
Architecture & System Design
| Document | Description | Status |
|---|---|---|
| ARCHITECTURE.md | System architecture overview | Current |
| ARCHITECTURE_PLAN.md | Architecture migration roadmap | Active |
| MULTI_TENANT_MIDDLEWARE.md | Multi-tenancy implementation | Current |
| KNOWLEDGE_ARCHITECTURE.md | Knowledge base and AI architecture | Current |
Security & Compliance
| Document | Description | Status |
|---|---|---|
| SECURITY_GUIDE.md | Security practices and guidelines | Current |
| RLS_POLICIES.md | Row-Level Security policies | Current |
| ACCOUNT_TOKEN_ENCRYPTION.md | Token encryption implementation | Current |
| INTERNAL_API_AUTHENTICATION.md | Internal API auth patterns | Current |
| auth-patterns.md | Authentication flow patterns | Current |
Database & Data
| Document | Description | Status |
|---|---|---|
| DATABASE_MIGRATIONS.md | Migration procedures and best practices | Current |
| DATABASE_RESILIENCE.md | Database reliability patterns | Current |
| VIEWING_DATABASE_IN_SUPABASE.md | Supabase database access guide | Current |
| lead-pipeline-schema.md | Lead pipeline data model | Current |
API & Integration
| Document | Description | Status |
|---|---|---|
| API_INTEGRATION_GUIDE.md | API integration patterns + webhooks | Current |
| API_VERSIONING.md | API versioning strategy | Current |
| API_MIGRATION_EXAMPLE.md | Response helpers migration guide | Current |
| WEBHOOK_IDEMPOTENCY.md | Idempotent webhook handling | Current |
| INTEGRATION_MONITORING.md | Integration health monitoring | Current |
| openapi.yaml | OpenAPI specification | Current |
| ml-api-openapi.yaml | ML API specification | Current |
Voice & Communications
| Document | Description | Status |
|---|---|---|
| VOICE_AI_SETUP.md | Voice AI configuration guide | Current |
| CALL_RECORDINGS.md | Call recording architecture | Current |
| SEQUENCE_LIMITATIONS.md | Autoresponder sequence limitations | Current |
Operations & Deployment
| Document | Description | Status |
|---|---|---|
| PRE_DEPLOYMENT_CHECKLIST.md | Deployment checklist | Current |
| BACKGROUND_JOBS.md | Background job patterns | Current |
| GIT_FLOW.md | Git workflow guidelines | Current |
| DEVELOPER_GUIDE.md | Developer onboarding guide | Current |
Business & Strategy
| Document | Description | Status |
|---|---|---|
| GTM_STRATEGY.md | Go-to-market strategy | Current |
| PRICING_MODEL.md | Pricing structure | Current |
| KNOWN_LIMITATIONS.md | Current limitations | Current |
| OWNERS.md | Feature ownership map | Template |
Testing Documentation
| Document | Description |
|---|---|
| e2e-onboarding-playwright.md | E2E 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.mdfor primary docslowercase-with-dashes.mdfor secondary/utility docs- OpenAPI specs use
.yamlextension
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
Related Resources
- Test Documentation: See root TESTING.md and
/tests/READMEs - Agent Instructions: See
/.claude/CLAUDE.md - Temporary Files: Use
/.tmp/(gitignored) for one-time reports