Tablez — C4 Architecture Diagrams¶

C4 model views of the Tablez platform at three zoom levels.

Level 1: System Context¶

Who interacts with Tablez?

C4Context
    title Tablez — System Context

    Person(guest, "Guest", "Books via web, chat, phone, or SMS")
    Person(staff, "Restaurant Staff", "Manages reservations and floor")
    Person(extai, "External AI Agent", "Books via MCP protocol")

    System(tablez, "Tablez", "AI-native restaurant reservation platform")

    System_Ext(twilio, "Twilio", "SMS delivery")
    System_Ext(claude, "Claude API", "AI reasoning")
    System_Ext(stripe, "Stripe", "Payments")

    Rel(guest, tablez, "Books tables")
    Rel(staff, tablez, "Manages floor")
    Rel(extai, tablez, "MCP tool calls")
    Rel(tablez, twilio, "Sends SMS")
    Rel(tablez, claude, "AI calls")
    Rel(tablez, stripe, "Payments")

    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="3")

Level 2: Container Diagram¶

What runs inside the platform?

C4Container
    title Tablez — Containers

    Person(user, "User", "Guest or Staff")

    System_Boundary(edge, "Edge") {
        Container(cf, "Cloudflare Tunnel", "cloudflared", "DNS, TLS, DDoS")
    }

    System_Boundary(tablez, "Tablez Platform") {
        Container(gateway, "API Gateway", "YARP / .NET 10", "Routes requests to services")
        Container(web, "Web App", "Next.js", "Dashboard and booking widget")
    }

    Rel(user, cf, "HTTPS")
    Rel(cf, gateway, "Tunnel")
    Rel(cf, web, "Tunnel")

    UpdateLayoutConfig($c4ShapeInRow="2", $c4BoundaryInRow="1")

Domain Services¶

C4Container
    title Tablez — Domain Services

    Container(gateway, "API Gateway", "YARP", "Incoming requests")

    System_Boundary(domain, "Domain Services") {
        Container(reservation, "Reservation", ".NET 10 / Marten", "Booking, waitlist, availability")
        Container(guest, "Guest", ".NET 10 / Marten", "Profiles, visit history")
        Container(restaurant, "Restaurant", ".NET 10", "Tables, hours, config")
        Container(ai, "AI Agent", "Semantic Kernel", "Chat, phone, messaging")
        Container(notification, "Notification", "Hangfire", "SMS, email, push")
    }

    System_Boundary(data, "Data") {
        ContainerDb(pg, "PostgreSQL", "Marten", "Events + projections")
        ContainerDb(vk, "Valkey", "Cache", "Pub/sub + cache")
    }

    Rel(gateway, reservation, "")
    Rel(gateway, guest, "")
    Rel(gateway, restaurant, "")
    Rel(gateway, ai, "")
    Rel(reservation, pg, "Events")
    Rel(guest, pg, "Events")
    Rel(reservation, vk, "Publish")
    Rel(vk, notification, "Subscribe")

    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

Event Flow¶

How services communicate (no direct calls):

flowchart LR
    R["Reservation"] -->|publish| VK["Valkey pub/sub"]
    VK -->|ReservationConfirmed| N["Notification"]
    VK -->|GuestSeated| W["Web (SignalR)"]
    VK -->|ReservationConfirmed| G["Guest"]
    VK -->|ReservationRequested| AI["AI Agent"]

Level 3: Reservation Service Components¶

Inside the most complex service — 4 IDesign layers:

C4Component
    title tablez-reservation — IDesign Layers

    Container_Boundary(clients, "Clients") {
        Component(ctrl, "ReservationsController", "ASP.NET", "REST endpoints")
    }

    Container_Boundary(managers, "Managers") {
        Component(create, "CreateReservation", "MediatR", "Create booking")
        Component(lifecycle, "Lifecycle Handlers", "MediatR", "Confirm, seat, cancel, complete")
        Component(queries, "Query Handlers", "MediatR", "Get reservation, availability")
    }

    Container_Boundary(engines, "Engines — Pure Logic") {
        Component(sm, "StateMachine", "Stateless", "Validates state transitions")
        Component(avail, "AvailabilityEngine", "Pure C#", "Calculates open slots")
    }

    Container_Boundary(ra, "Resource Access") {
        Component(store, "MartenEventStore", "Marten", "Append + read events")
        Component(proj, "ReservationProjection", "Marten", "Build read model")
    }

    Rel(ctrl, create, "MediatR.Send")
    Rel(ctrl, lifecycle, "MediatR.Send")
    Rel(ctrl, queries, "MediatR.Send")
    Rel(create, sm, "Validate")
    Rel(create, avail, "Check slots")
    Rel(create, store, "Append event")
    Rel(lifecycle, sm, "Validate")
    Rel(lifecycle, store, "Append event")
    Rel(queries, proj, "Read")

    UpdateLayoutConfig($c4ShapeInRow="2", $c4BoundaryInRow="1")

Actors¶

Actor	Channel	Interaction
Guest	Web widget, AI chat, phone, SMS	Browse availability, book, cancel, join waitlist
Restaurant Staff	Staff dashboard (web)	Manage floor, seat guests, mark arrivals, handle waitlist
Restaurant Owner	Staff dashboard (web)	Configure tables/hours, view analytics, manage settings
External AI Agent	MCP protocol	Check availability, create reservations on behalf of users

External Dependencies¶

System	Purpose	Integration
PostgreSQL	Event store (Marten) + read model projections	Direct connection
Valkey	Cache + pub/sub for event-driven communication	Direct connection
Claude API	LLM reasoning for AI reservation agent	HTTP via Semantic Kernel
Twilio	SMS confirmations, reminders, waitlist offers	HTTP API
Stripe	No-show fees, ticketed event payments	HTTP API
Cloudflare	DNS, TLS, DDoS protection, tunnel ingress	cloudflared DaemonSet