Skip to main content

CODITECT Multi-Tenant SaaS Architecture - Document Index

Complete inventory of all architecture documentation, diagrams, workflows, and supporting materials.

Last Updated: December 25, 2024 Total Documents: 25+ files Total Diagrams: 60 Total Workflows: 8

Table of Contents​

  1. Architecture Documents
  2. Business Documents
  3. Workflow Documentation
  4. Diagrams
  5. n8n Workflow Files
  6. Related ADRs
  7. Quick Reference

Architecture Documents​

Core Architecture​

DocumentDescriptionLocation
ADR-009: Multi-Tenant SaaS ArchitectureMaster architecture decision record covering data model, auth, provisioning, payments, and API designADR-009
SDD: Software Design DocumentC4 model architecture with context, container, and component diagramsSDD
TDD: Technical Design DocumentDetailed technical specifications, sequence diagrams, and class diagramsTDD
Workflow Diagrams25 Mermaid diagrams covering all business processesWorkflow Diagrams

Supporting ADRs​

ADRTitleKey Decision
ADR-010Cloud Workstations ArchitectureGCP Workstations with tier-based configurations
ADR-011Authentication StrategyFirebase Auth + Google Identity Platform
ADR-012Data Isolation StrategyPostgreSQL RLS with org_id tenant isolation
ADR-013Event-Driven ArchitectureGoogle Pub/Sub for async processing

Business Documents​

DocumentDescriptionLocation
CODITECT Business Plan8-page business plan covering market, pricing, and system architectureBusiness Plan

Key Business Sections​

  • Executive Summary
  • Business Model (AZ1.AI as billing entity)
  • Pricing Tiers ($29-$299/month + Enterprise)
  • Payment-Driven Automation
  • Cost Analysis & Margins
  • Go-to-Market Strategy

Workflow Documentation​

Narrative Guides​

Detailed step-by-step documentation for each automated workflow:

Workflow IDNameDescriptionNarrativen8n JSON
WF-001User RegistrationNew user signup and org creationNarrativeJSON
WF-002Subscription CheckoutStripe checkout session and upgradeNarrativeJSON
WF-003Stripe Webhook HandlerPayment event routingNarrativeJSON
WF-004Workstation ProvisioningGCP workstation creationNarrativeJSON
WF-005User InvitationTeam member invitationsNarrativeJSON
WF-006Auditor AccessCompliance auditor grantsNarrativeJSON
WF-007GDPR Data RequestData access/erasureNarrativeJSON
WF-008User OffboardingAutomated cleanupNarrativeJSON
WF-009Email VerificationVerify email after registrationNarrativeJSON
WF-010Password ResetForgot password recoveryNarrativeJSON
WF-021Subscription UpgradeMid-cycle plan upgrade with prorationNarrativeJSON
WF-023Subscription CancellationCancel with retention offerNarrativeJSON
WF-024Payment Method UpdateUpdate card with retryNarrativeJSON
WF-025Failed Payment RetrySmart retry & grace periodNarrativeJSON
WF-031Workstation StartStart stopped workstationNarrativeJSON
WF-032Workstation StopManual workstation stopNarrativeJSON
WF-037Workstation DeletionDelete with final backupNarrativeJSON
WF-038Workstation Access URLGenerate signed access URLNarrativeJSON
WF-039Idle Detection & Auto-StopAuto-stop idle workstationsNarrativeJSON
WF-054GDPR Data ExportUser data export (Article 15)NarrativeJSON
WF-055Security Incident DetectionReal-time threat detectionNarrativeJSON
WF-066Incident ResponseStatus page & communicationNarrativeJSON
WF-072Database BackupDaily backup with restore testingNarrativeJSON

Diagrams​

Diagram Index​

Complete index of all 60 architecture diagrams:

Location: Diagram Index

Diagram Categories​

CategoryCountDescription
Workflow Diagrams25Business process flows
ADR-010 Diagrams4Cloud workstations architecture
ADR-011 Diagrams4Authentication flows
ADR-012 Diagrams4Data isolation patterns
ADR-013 Diagrams3Event-driven architecture
SDD Diagrams10C4 model architecture
TDD Diagrams10Technical design details

Diagram Formats​

Each diagram available in three formats:

FormatLocationUse Case
Mermaid (.mmd)architecture/diagrams/mermaid/Source files, version control
PNG (.png)architecture/diagrams/png/Documentation embedding
SVG (.svg)architecture/diagrams/svg/Scalable web/print

Key Workflow Diagrams​

#DiagramFile
01Business Model OverviewPNG
02User Registration SequencePNG
03User State MachinePNG
04Payment Flow SequencePNG
05Billing Cycle FlowchartPNG
06AZ1.AI to Google Payment FlowPNG
07Auto-Provisioning SequencePNG
08Provisioning State MachinePNG

n8n Workflow Files​

Importable JSON Workflows​

Ready-to-import n8n workflow definitions:

WorkflowFileNodesTrigger
WF-001: User RegistrationJSON7Webhook POST
WF-002: Subscription CheckoutJSON7Webhook POST
WF-003: Stripe Webhook HandlerJSON11Webhook POST
WF-004: Workstation ProvisioningJSON10Pub/Sub
WF-005: User InvitationJSON7Webhook POST
WF-006: Auditor AccessJSON6Webhook POST
WF-007: GDPR Data RequestJSON12Webhook POST
WF-008: User OffboardingJSON11Schedule (hourly)

n8n Credentials Required​

CredentialTypeUsed By
CODITECT PostgreSQLpostgresAll workflows
GCP OAuthgoogleOAuth2ApiWF-004, WF-008
GCS OAuthgoogleCloudStorageOAuth2ApiWF-007, WF-008
GCP Pub/SubgoogleCloudPubSubOAuth2ApiWF-003, WF-004, WF-005
Stripe APIstripeApiWF-002, WF-003

Cloud Platform ADRs​

ADRTitleLocation
ADR-009Multi-Tenant SaaS ArchitectureADR-009
ADR-010Cloud Workstations ArchitectureADR-010
ADR-011Authentication StrategyADR-011
ADR-012Data Isolation StrategyADR-012
ADR-013Event-Driven ArchitectureADR-013

Quick Reference​

Document Relationships​

CODITECT Architecture Documentation
│
├── ADR-009 (Master Architecture)
│   ├── SDD (Design Specification)
│   ├── TDD (Technical Details)
│   ├── ADR-010 (Workstations)
│   ├── ADR-011 (Authentication)
│   ├── ADR-012 (Data Isolation)
│   └── ADR-013 (Events)
│
├── Business Plan
│   └── References ADR-009 architecture
│
├── Workflow Diagrams (25)
│   └── Visual representation of all processes
│
├── n8n Workflows (8)
│   └── Executable workflow definitions
│
└── Narrative Guides (8)
    └── Step-by-step documentation

Naming Conventions​

TypePatternExample
ADRsADR-NNN-kebab-caseADR-009-multi-tenant-saas-architecture
WorkflowsWF-NNN-kebab-caseWF-001-user-registration
DiagramsNN-kebab-case01-business-model-overview
NarrativesWF-NNN-kebab-case.mdWF-001-user-registration.md

File Counts Summary​

CategoryCount
ADR Documents5
Design Documents (SDD/TDD)2
Business Documents1
Workflow Narratives8
n8n JSON Workflows8
Mermaid Diagrams60
PNG Images60
SVG Images60
Total Files~204

Maintenance Notes​

Keeping Documents in Sync​

When making changes, update in order:

  1. ADR-009 (master architecture decisions)
  2. SDD/TDD (design documents)
  3. Workflow Diagrams (Mermaid sources)
  4. n8n Workflows (JSON files)
  5. Narratives (step-by-step guides)
  6. This Index (document inventory)

Regenerating Diagrams​

# Extract and convert all diagrams
python3 scripts/extract-all-diagrams.py

# Verify all diagrams exist
ls -la docs/architecture/diagrams/png/ | wc -l  # Should be 60+

Adding New Workflows​

  1. Create n8n JSON in workflows/n8n/WF-NNN-name.json
  2. Create narrative in workflows/narratives/WF-NNN-name.md
  3. Add diagram to architecture/CODITECT-WORKFLOW-DIAGRAMS.md
  4. Run diagram extraction script
  5. Update this index

Document Version: 1.0 Created: December 25, 2024 Maintainer: CODITECT Architecture Team