C4 Architecture Diagrams

Formal architecture views following the C4 model (Context, Container, Component, Code). These diagrams provide progressively detailed views of the platform for technical documentation and academic reference. We omit Code-level diagrams as they are not manually maintainable and do not add value beyond IDE-generated views of the codebase.

Level 1 — System Context

Who uses RELab, and what external services does it depend on?

C4Context
    title System Context — RELab

    Person(researcher, "Researcher", "Collects and manages product data via the app")
    Person(visitor, "Public Visitor", "Browses published products, landing page, and docs")
    Person(admin, "Admin", "Manages users, reference data, and cameras via API")

    System(relab, "RELab Platform", "Research data collection and publication platform")

    System_Ext(oauth, "OAuth Providers", "Google and GitHub social login")
    System_Ext(smtp, "SMTP Server", "Transactional email delivery")
    System_Ext(youtube, "YouTube API", "Live stream management for camera feeds")
    System_Ext(have-i-been-pwnd, "Have I Been Pwned", "Password breach checking (k-anonymity)")
    System_Ext(rpi, "Raspberry Pi Cameras", "Remote camera hardware for image capture")

    Rel(researcher, relab, "Collects data, uploads media")
    Rel(visitor, relab, "Browses products and documentation")
    Rel(admin, relab, "Administers platform")
    Rel(relab, oauth, "Authenticates users", "HTTPS")
    Rel(relab, smtp, "Sends verification and notification emails", "SMTP")
    Rel(relab, youtube, "Creates and monitors live streams", "HTTPS")
    Rel(relab, have-i-been-pwnd, "Validates password safety", "HTTPS")
    Rel(relab, rpi, "Captures images, manages streams", "HTTP")

    UpdateRelStyle(researcher, relab, $offsetY="-30")
    UpdateRelStyle(visitor, relab, $offsetY="-30")
    UpdateRelStyle(admin, relab, $offsetY="-30")

Level 2 — Container Diagram

What are the major deployable units inside the platform, and how do they interact?

C4Container
    title Container Diagram — RELab

    Person(researcher, "Researcher", "")
    Person(visitor, "Public Visitor", "")
    Person(admin, "Admin", "")

    System_Boundary(relab, "RELab Platform") {
        Container(app, "Expo App", "React Native / Expo Router", "Data collection UI and public product browsing")
        Container(web, "Astro Landing Page", "Astro", "Public marketing and landing page")
        Container(docs, "Astro Starlight Docs", "Astro", "Project documentation site")

        Container(backend, "FastAPI Backend", "Python / FastAPI", "REST API: auth, data collection, file management, plugins")

        ContainerDb(postgres, "PostgreSQL", "Relational database", "Products, users, file metadata, reference data")
        ContainerDb(redis, "Redis", "In-memory store", "API cache, refresh tokens, session state")
        ContainerDb(filestorage, "File Storage", "Filesystem / S3", "User-uploaded images and media")
    }

    System_Ext(oauth, "OAuth Providers", "Google, GitHub")
    System_Ext(smtp, "SMTP Server", "Email delivery")
    System_Ext(youtube, "YouTube API", "Live streaming")
    System_Ext(rpi, "Raspberry Pi Cameras", "Image capture hardware")

    Rel(researcher, app, "Collects data", "HTTPS")
    Rel(visitor, app, "Browses products", "HTTPS")
    Rel(visitor, web, "Reads landing page", "HTTPS")
    Rel(visitor, docs, "Reads documentation", "HTTPS")
    Rel(admin, backend, "Admin API calls", "HTTPS")

    Rel(app, backend, "API requests", "HTTPS / JSON")
    Rel(web, backend, "Selected API usage", "HTTPS / JSON")

    Rel(backend, postgres, "Queries and persists data", "asyncpg")
    Rel(backend, redis, "Cache and token storage", "TCP")
    Rel(backend, filestorage, "Upload, process, delete media")
    Rel(backend, oauth, "Social login", "HTTPS OAuth2")
    Rel(backend, smtp, "Sends email", "SMTP")
    Rel(backend, youtube, "Manages streams", "HTTPS")
    Rel(backend, rpi, "Captures images", "HTTP")

Level 3 — Component Diagram (Backend)

What are the domain modules inside the FastAPI backend, and how do they relate to each other and to external services?

C4Component
    title Component Diagram — FastAPI Backend

    Container_Boundary(backend, "FastAPI Backend") {
        Component(auth, "Auth Module", "FastAPI-Users", "Login, registration, OAuth, email verification, password reset, user and organisation management")
        Component(datacollection, "Data Collection", "SQLAlchemy / FastAPI", "Products, components, associations, search, user-scoped CRUD")
        Component(backgrounddata, "Background Data", "SQLAlchemy / FastAPI", "Taxonomies, categories, materials, product types — cached reference data")
        Component(filestorage, "File Storage", "FastAPI", "File and image upload, on-the-fly resizing, WebP conversion, periodic orphan cleanup")
        Component(newsletter, "Newsletter", "FastAPI", "Subscription management, double opt-in confirmation, broadcast emails")
        Component(rpi-cam, "RPI Camera Plugin", "FastAPI", "Camera CRUD, remote capture, YouTube live stream integration, recording sessions")
        Component(common, "Common Infrastructure", "FastAPI", "Shared CRUD utilities, health checks, error handling, OpenAPI helpers, file serving")
        Component(core, "Core", "Python", "Config, database engine, Redis client, cache, HTTP client, telemetry, background task runner")
    }

    ContainerDb(postgres, "PostgreSQL", "", "")
    ContainerDb(redis, "Redis", "", "")
    ContainerDb(filestorage_vol, "File Storage", "", "")

    System_Ext(oauth, "OAuth Providers", "")
    System_Ext(smtp, "SMTP Server", "")
    System_Ext(youtube, "YouTube API", "")
    System_Ext(rpi, "RPi Cameras", "")

    Rel(auth, core, "Sessions, config, email")
    Rel(datacollection, backgrounddata, "References categories, materials, types")
    Rel(datacollection, filestorage, "Product images")
    Rel(rpi-cam, filestorage, "Stores captured images")
    Rel(rpi-cam, datacollection, "Links cameras to products")
    Rel(rpi-cam, auth, "YouTube OAuth tokens")
    Rel(newsletter, auth, "Email sending infrastructure")

    Rel(core, postgres, "Async connection pool", "asyncpg")
    Rel(core, redis, "Cache + token storage", "TCP")
    Rel(filestorage, filestorage_vol, "Read / write media")
    Rel(auth, oauth, "Social login", "HTTPS")
    Rel(auth, smtp, "Verification and reset emails", "SMTP")
    Rel(newsletter, smtp, "Subscription and broadcast emails", "SMTP")
    Rel(rpi-cam, youtube, "Stream management", "HTTPS")
    Rel(rpi-cam, rpi, "Image capture and control", "HTTP")