# m8ke/aircloud architecture

> Architecture diagram of the GitHub repository m8ke/aircloud, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/m8ke/aircloud
- Repository: https://github.com/m8ke/aircloud

## Overview

##### Project type and purpose
- This is a full-stack, self-hostable, web-based P2P file-sharing application (“AirCloud”) built on WebRTC.
- The client is an Angular SPA; the server is a Spring Boot WebSocket signaling service; auxiliary services include TURN/STUN (Coturn) and Nginx as a proxy/reverse-proxy.

##### File-structure highlights
- Top-level:
- client/ → Angular application (TypeScript, components, services, utils, assets, Dockerfile)
- server/ → Spring Boot (Java, WebSocket signaling, DTOs, application.yml, Dockerfile)
- nginx/ → templates and configs for reverse-proxy and cert management
- docker-compose.yml & docker-compose.dev.yml → orchestrate client, server, coturn, nginx
- .github/workflows → CI/CD for client, server, deploy

##### Key insights from README
- Core architecture:
- Frontend: Angular + WebRTC (data-channel + Zip.js)
- Backend: Spring Boot + WebSocket signaling
- TURN/STUN via Coturn for NAT traversal
- Nginx for TLS termination / reverse proxy / static asset hosting
- No persistent storage; ephemeral sessions, end-to-end encrypted P2P transfer.

- Angular Client (Browser)
- Nginx Reverse Proxy
- Spring Boot Signaling Server (WebSocket)
- Coturn (TURN/STUN) Service
- Peer Browser (second client endpoint)
- (Optional) Certbot / Let's Encrypt ACME
1. User’s Browser ↔︎ Nginx (HTTPS)
2. Nginx ↔︎ Angular assets (static files)
3. Browser’s Angular code → WebSocket handshake → Nginx → Signaling Server
4. Signaling Server ↔︎ other peers via WebSocket (exchange SDP, ICE candidates)
5. Browsers ↔︎ TURN/STUN (via ICE) to establish direct P2P DataChannel
6. Browser ↔︎ Browser (WebRTC DataChannel) for encrypted file transfers
c. Architectural patterns & design principles:
- Layered separation: Reverse proxy → API (signaling) → P2P network
- Event-driven WebSocket signaling
- Microservices-style deployment via Docker Compose
- No central storage: ephemeral, in-memory sessions only
d. Technologies & frameworks:
- Angular (client SPA) / TypeScript
- WebRTC API & Zip.js (client-side bundling + encryption)
- Spring Boot WebSocket (server)
- Coturn (TURN/STUN)
- Nginx + Docker + Docker Compose
- GitHub Actions (CI/CD)

##### Detail-capture checklist
- Docker Compose grouping: client, server, coturn, nginx.
- Ports: 80/443 (Nginx), 8080 or WSS port (signaling), 3478 UDP/TCP (Coturn).
- Optional Certbot container or ACME flow if self-hosting HTTPS.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Public Internet Boundary
    subgraph "Public Internet"
        direction TB
        B1["Angular SPA (Browser A)"]:::client
        B2["Angular SPA (Browser B)"]:::client
    end

    %% Internal Services Group
    subgraph "AirCloud Services (Docker Compose)"
        direction TB
        Nginx["Nginx Reverse Proxy (HTTPS)"]:::server
        Signaling["WebSocket Signaling Server"]:::server
        Coturn["Coturn (TURN/STUN)"]:::ext
        Certbot["Certbot (ACME)"]:::ext
        Compose["Docker Compose\n(docker-compose.yml,\n docker-compose.dev.yml)"]:::server
    end

    GH["GitHub Actions CI/CD"]:::ext

    %% Connections
    B1 -->|"HTTPS GET /index.html"| Nginx
    Nginx -->|"serves static assets"| B1

    B2 -->|"HTTPS GET /index.html"| Nginx
    Nginx -->|"serves static assets"| B2

    B1 -->|"WSS handshake (SDP/ICE)"| Nginx
    Nginx -->|"proxy WSS"| Signaling
    Signaling -->|"WSS: SDP/ICE exchange"| B1
    Signaling -->|"WSS: SDP/ICE exchange"| B2

    B1 -->|"ICE connectivity checks"| Coturn
    B2 -->|"ICE connectivity checks"| Coturn

    B1 -->|"WebRTC DataChannel (file chunks)"| B2

    Compose -->|orchestrates| Nginx
    Compose -->|orchestrates| Signaling
    Compose -->|orchestrates| Coturn
    Compose -->|orchestrates| Certbot

    GH -->|CI/CD pipelines| Compose

    %% Click Events
    click B1 "https://github.com/m8ke/aircloud/tree/master/client/"
    click B2 "https://github.com/m8ke/aircloud/tree/master/client/"
    click Signaling "https://github.com/m8ke/aircloud/tree/master/server/"
    click Nginx "https://github.com/m8ke/aircloud/tree/master/nginx/"
    click Coturn "https://github.com/m8ke/aircloud/blob/master/nginx/coturn.conf"
    click Compose "https://github.com/m8ke/aircloud/blob/master/docker-compose.yml"
    click Compose "https://github.com/m8ke/aircloud/blob/master/docker-compose.dev.yml"
    click GH "https://github.com/m8ke/aircloud/tree/master/.github/workflows/"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef server fill:#DFFFE0,stroke:#22863A,stroke-width:1px
    classDef ext fill:#FFEFD5,stroke:#CB4B16,stroke-width:1px
```
