Skip to content

Smartsapp Documentation

System Overview (C1/C2)

Smartsapp — C4 Architecture¶

System-wide architecture document using the C4 model. This document covers C1 (System Context) and C2 (Container) levels. Each module maintains its own C3 (Component) and C4 (Code) documentation.

C1 — System Context¶

The Smartsapp platform and its external actors and systems.

C4Context
    title Smartsapp — System Context

    Person(admin, "School Admin", "Manages schools, campuses, staff, and operations")
    Person(parent, "Parent / Guardian", "Views student info, pays invoices, manages pickups")
    Person(teacher, "Teacher / Staff", "Accesses classroom data, takes attendance, creates reports")
    Person(student, "Student", "Interacts with canteen, receives reports")

    System(smartsapp, "Smartsapp System", "Backend platform: school management, canteen, attendance, invoicing, academic reports, pickup management, chat, and engagement")

    System_Ext(keycloak, "Keycloak", "Authentication & authorization (OAuth/OIDC, SSO, user federation)")
    System_Ext(novu, "Novu", "Multi-channel notifications and messaging")
    System_Ext(hyperswitch, "Hyperswitch", "Payment routing and processing")
    System_Ext(formance, "Formance", "Wallet and double-entry ledger")

    Rel(admin, smartsapp, "Manages data via", "REST API")
    Rel(parent, smartsapp, "Views info & pays via", "REST API")
    Rel(teacher, smartsapp, "Records data via", "REST API")
    Rel(student, smartsapp, "Interacts via", "REST API")
    Rel(smartsapp, keycloak, "Authenticates users via", "OAuth/OIDC")
    Rel(smartsapp, novu, "Sends notifications via", "API")
    Rel(smartsapp, hyperswitch, "Processes payments via", "API")
    Rel(smartsapp, formance, "Manages wallets via", "API")

C2 — Container¶

The runtime containers that make up the Smartsapp backend.

C4Container
    title Smartsapp — Container Diagram

    Person(user, "User", "Admin, parent, teacher, staff, or student")

    Container_Boundary(backend, "Backend System") {
        Container(app, "Spring Boot App", "Java 21, Spring Boot", "Hosts all modules. Port 8080")
        ContainerDb(postgres, "PostgreSQL", "v16-alpine", "Primary application database")
        Container(kafka, "Redpanda (Kafka)", "v24.1.1", "Event streaming and async messaging")
        Container(redis, "Redis", "v7-alpine", "Cache layer and session store")
    }

    Container_Boundary(observability, "Observability") {
        Container(grafana, "Grafana", "", "Dashboards for metrics, logs, and traces")
        Container(prometheus, "Prometheus", "", "Metrics collection")
        Container(loki, "Loki", "", "Log aggregation")
        Container(tempo, "Tempo", "", "Distributed tracing")
        Container(sentry, "Sentry", "", "Error tracking and performance")
    }

    Container_Boundary(data, "Data & Analytics") {
        Container(posthog, "PostHog", "", "Product analytics, events, funnels")
        Container(metabase, "Metabase", "", "BI dashboards and ad-hoc queries")
        Container(airbyte, "Airbyte", "", "ETL and data warehouse")
    }

    Rel(user, app, "REST API", "HTTPS / JSON")
    Rel(app, postgres, "Reads/writes", "JDBC")
    Rel(app, kafka, "Publishes/consumes events", "Kafka protocol")
    Rel(app, redis, "Caches data", "Redis protocol")
    Rel(app, grafana, "Monitored by")
    Rel(app, sentry, "Reports errors to")

Container	Technology	Address	Purpose
Spring Boot App	Java 21, Spring Boot	`localhost:8080`	REST API, business logic, all modules
PostgreSQL	v16-alpine	`localhost:5432`	Primary database (db: `system`)
Redpanda (Kafka)	v24.1.1	`localhost:19092`	Event streaming
Redpanda Console	v2.5.2	`localhost:8085`	Kafka topic management UI
Redis	v7-alpine	`localhost:6379`	Caching and session store

Spring Boot module structure¶

The Spring Boot app is organized into self-contained modules:

modules/
├── customer/          # Customer-facing modules
│   ├── school/        # School management (SMIS)
│   ├── canteen/       # Canteen ordering and management
│   ├── attendance/    # Student attendance tracking (check-in/out, pickup persons)
│   ├── academicreport/# Academic reports and grading
│   └── invoice/       # Billing and invoicing
├── platform/          # Platform infrastructure modules
│   ├── auth/          # Authentication and authorization
│   ├── chat/          # Real-time messaging
│   ├── engagement/    # User engagement features
│   ├── notifications/ # Notification orchestration
│   └── wallet/        # Wallet and payments
├── shared/            # Cross-module utilities (PagedResponse, ResourceNotFoundException)
└── sample/            # Reference implementation template

Module C3/C4 Documentation¶

Each module maintains its own C3 (Component) and C4 (Code) architecture documentation. All modules follow the flat package structure defined in the backend/src/main/java/com/smartsapp/system/modules/sample/README.md.

Customer modules¶

Module	C3/C4 Architecture	Status
School	school-c4-architecture.md	Available
Canteen	canteen-c4-architecture.md	Available
Academic Report	—	Pending
Student Attendance	—	Pending
Invoice	—	Pending

Platform modules¶

Module	C3/C4 Architecture	Status
Auth	—	Pending
Chat	—	Pending
Engagement	—	Pending
Notifications	—	Pending
Wallet	—	Pending

Document	Path
Project README	`README.md` (repo root)
PRD index	docs/PRD.md
Backend system	`backend/README.md`
Sample module	`backend/src/main/java/com/smartsapp/system/modules/sample/README.md`
CI/CD	docs/CICD.md
AI context	docs/AI_CONTEXT.md