Skip to content

Cuti-E Architecture Documentation

This directory contains C4 model architecture diagrams for the Cuti-E platform.

What is the C4 Model?

The C4 model is a simple approach to documenting software architecture using four levels of abstraction:

Level Name Audience Shows
1 Context Everyone System + users + external systems
2 Container Technical staff Applications, databases, APIs
3 Component Developers Internal modules within containers
4 Code Developers Class diagrams (optional)

Diagrams

Note: PNG and SVG versions are auto-generated by CI when .puml files change.

Level 1: System Context

Files: c4-context.puml | PNG | SVG

Shows the Cuti-E platform in relation to its users and external systems: - Users: App Users, App Developers, Super Admins - External Systems: Apple Services, Google Services, Client Apps

System Context

Level 2: Container

Files: c4-containers.puml | PNG | SVG

Shows the high-level technical building blocks: - API (Cloudflare Workers) - D1 Database - Notification Queue (Cloudflare Queues) - Admin Dashboard (Cloudflare Pages) - Marketing Website - iOS SDK, Android SDK - iOS Admin App, Android Admin App

Containers

Level 3: Components

Container Source Rendered Key Components
API puml PNG / SVG Router, Handlers, Middleware, Services, Notifications
iOS SDK puml PNG / SVG CutiE, APIClient, AppAttest, PushNotifications, Views
Android SDK puml PNG / SVG CutiE, APIClient, Compose Views, Models, OkHttp
Admin Dashboard puml PNG / SVG Pages, Modules, Services, Security

API Components

API Components

iOS SDK Components

iOS SDK Components

Android SDK Components

Android SDK Components

Admin Dashboard Components

Admin Dashboard Components

Viewing Diagrams

Option 1: PlantUML Online Server

Copy the .puml file contents and paste into: - https://www.plantuml.com/plantuml/uml/

Option 2: VS Code Extension

  1. Install "PlantUML" extension
  2. Open .puml file
  3. Press Alt+D to preview

Option 3: Command Line

# Install PlantUML
brew install plantuml

# Render to PNG
plantuml c4-context.puml

Option 4: GitHub Action (Automated)

The .github/workflows/render-diagrams.yml workflow automatically renders diagrams on push.

Updating Diagrams

When to Update

Change Type Update Required
New container (app, service, database) Container diagram
New external integration (API, service) Context + Container diagrams
New handler/module in API API Component diagram
New view/service in SDK SDK Component diagram
New page/module in Dashboard Dashboard Component diagram
Security feature added Note in relevant diagram

How to Update

  1. Edit the relevant .puml file
  2. Use PlantUML C4 syntax (see C4-PlantUML)
  3. Preview locally to verify
  4. Commit changes
  5. CI will render new PNGs automatically

PlantUML C4 Syntax Quick Reference

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml

' Define elements
Person(alias, "Label", "Description")
System(alias, "Label", "Description")
System_Ext(alias, "Label", "Description")
Container(alias, "Label", "Technology", "Description")
ContainerDb(alias, "Label", "Technology", "Description")
Component(alias, "Label", "Technology", "Description")

' Define relationships
Rel(from, to, "Label")
Rel(from, to, "Label", "Technology")

' Show legend
SHOW_LEGEND()
@enduml

Architecture Decision Records

Key architectural decisions are documented in: - CLAUDE.md - Main project instructions with decision table - Individual GitHub issues for significant changes

Key Decisions

Date Decision Rationale
2025-11 Polling over WebSocket SSE exposed tokens in URL; polling with Authorization header is more secure
2025-11 SSL pinning to root CAs Root CAs have 10+ year validity, safer than leaf certificates
2025-11 XSS prevention via escapeHtml() All user content escaped before rendering
2025-12 Device secret authentication Challenge-response prevents device ID spoofing

Diagram Ownership

These diagrams are maintained by the development team. When making architectural changes:

  1. Update the relevant diagram(s)
  2. Include diagram updates in your PR
  3. Reference the updated diagrams in PR description

Questions?

If you're unsure how to update a diagram or where a component belongs, check: 1. Existing diagrams for patterns 2. CLAUDE.md for context 3. Ask in the PR review