# pskth/event-driven-file-sharing architecture

> Architecture diagram of the GitHub repository pskth/event-driven-file-sharing, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pskth/event-driven-file-sharing
- Repository: https://github.com/pskth/event-driven-file-sharing

## Overview

This is a serverless, temporary file-sharing system: a sender requests an upload link, transfers the file directly to S3, and shares a short code; a recipient exchanges that code for a download link and downloads directly from S3. The gatekeeper coordinates presigned URLs and metadata, while DynamoDB TTL expiration drives cleanup of stored files. The excerpts show the web, gatekeeper, download, and cleanup implementations. The TTL-to-cleanup event wiring is documented in the README, not shown in the sampled source.

Main entry points: [`src/web_app/server.py`](https://github.com/pskth/event-driven-file-sharing/blob/main/src/web_app/server.py) (Web broker), [`src/web_app/static/app.js`](https://github.com/pskth/event-driven-file-sharing/blob/main/src/web_app/static/app.js) (Sharing interface), [`src/gatekeeper_api/app.py`](https://github.com/pskth/event-driven-file-sharing/blob/main/src/gatekeeper_api/app.py) (Upload gatekeeper), [`src/download_handler/app.py`](https://github.com/pskth/event-driven-file-sharing/blob/main/src/download_handler/app.py) (Download handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web_ui["Sharing interface<br/>[app.js]"]
  node_web_page["Web page<br/>[index.html]"]
  node_web_server["Web broker<br/>[server.py]"]
end

subgraph group_api["Link services"]
  node_gatekeeper["Upload gatekeeper<br/>[app.py]"]
  node_download_handler["Download handler<br/>[app.py]"]
end

subgraph group_storage["File and metadata storage"]
  node_s3[("S3 file bucket")]
  node_metadata[("DynamoDB metadata")]
end

subgraph group_lifecycle["Expiration cleanup"]
  node_cleanup["Automated cleanup<br/>[app.py]"]
end

node_sender(("Sender / recipient"))

node_sender -->|"uses"| node_web_ui
node_web_server -->|"renders"| node_web_page
node_web_ui -->|"requests links"| node_web_server
node_web_server -->|"invokes upload"| node_gatekeeper
node_web_server -->|"invokes download"| node_download_handler
node_gatekeeper -->|"creates upload URL"| node_s3
node_gatekeeper -->|"writes status"| node_metadata
node_download_handler -->|"reads record"| node_metadata
node_download_handler -->|"creates download URL"| node_s3
node_web_ui -->|"transfers directly"| node_s3
node_metadata -->|"TTL removal triggers"| node_cleanup
node_cleanup -->|"deletes expired file"| node_s3

click node_web_ui "https://github.com/pskth/event-driven-file-sharing/blob/main/src/web_app/static/app.js"
click node_web_page "https://github.com/pskth/event-driven-file-sharing/blob/main/src/web_app/templates/index.html"
click node_web_server "https://github.com/pskth/event-driven-file-sharing/blob/main/src/web_app/server.py"
click node_gatekeeper "https://github.com/pskth/event-driven-file-sharing/blob/main/src/gatekeeper_api/app.py"
click node_download_handler "https://github.com/pskth/event-driven-file-sharing/blob/main/src/download_handler/app.py"
click node_cleanup "https://github.com/pskth/event-driven-file-sharing/blob/main/src/automated_cleanup/app.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web_ui,node_web_page,node_web_server toneBlue
class node_gatekeeper,node_download_handler toneAmber
class node_s3,node_metadata toneMint
class node_cleanup toneRose
class node_sender toneIndigo
```

## Components

### Web client

- [Sharing interface](https://github.com/pskth/event-driven-file-sharing/blob/main/src/web_app/static/app.js): `src/web_app/static/app.js`
- [Web page](https://github.com/pskth/event-driven-file-sharing/blob/main/src/web_app/templates/index.html): `src/web_app/templates/index.html`
- [Web broker](https://github.com/pskth/event-driven-file-sharing/blob/main/src/web_app/server.py): `src/web_app/server.py`

### Link services

- [Upload gatekeeper](https://github.com/pskth/event-driven-file-sharing/blob/main/src/gatekeeper_api/app.py): `src/gatekeeper_api/app.py`
- [Download handler](https://github.com/pskth/event-driven-file-sharing/blob/main/src/download_handler/app.py): `src/download_handler/app.py`

### File and metadata storage

- **S3 file bucket**
- **DynamoDB metadata**

### Expiration cleanup

- [Automated cleanup](https://github.com/pskth/event-driven-file-sharing/blob/main/src/automated_cleanup/app.py): `src/automated_cleanup/app.py`

### Other components

- **Sender / recipient**

## Connections

- Sender / recipient → Sharing interface: uses (evidence: `src/web_app/static/app.js`)
- Web broker → Web page: renders (evidence: `src/web_app/server.py`)
- Sharing interface → Web broker: requests links (evidence: `src/web_app/static/app.js`)
- Web broker → Upload gatekeeper: invokes upload (evidence: `src/web_app/server.py`)
- Web broker → Download handler: invokes download (evidence: `src/web_app/server.py`)
- Upload gatekeeper → S3 file bucket: creates upload URL (evidence: `src/gatekeeper_api/app.py`)
- Upload gatekeeper → DynamoDB metadata: writes status (evidence: `src/gatekeeper_api/app.py`)
- Download handler → DynamoDB metadata: reads record (evidence: `src/download_handler/app.py`)
- Download handler → S3 file bucket: creates download URL (evidence: `src/download_handler/app.py`)
- Sharing interface → S3 file bucket: transfers directly (evidence: `src/web_app/static/app.js`)
- DynamoDB metadata → Automated cleanup: TTL removal triggers (evidence: `README.md`)
- Automated cleanup → S3 file bucket: deletes expired file (evidence: `src/automated_cleanup/app.py`)
