# bsitcmu-26-27/shuna-backend architecture

> Architecture diagram of the GitHub repository bsitcmu-26-27/shuna-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bsitcmu-26-27/shuna-backend
- Repository: https://github.com/bsitcmu-26-27/shuna-backend

## Overview

Shuna Backend is the CMU BSIT booth’s freedom-wall backend. Visitors submit text posts, optionally with an image; the backend verifies Turnstile, compresses and stores images, saves post data, and serves posts and reactions. Administrators can open the served admin page and use post-management endpoints. The sampled source shows the API and storage calls; README-listed frontend changes describe a separate client and are not mapped as backend components.

Main entry points: [`main.py`](https://github.com/bsitcmu-26-27/shuna-backend/blob/main/main.py) (Post endpoints), [`routes/admin.py`](https://github.com/bsitcmu-26-27/shuna-backend/blob/main/routes/admin.py) (Admin page route), [`app.py`](https://github.com/bsitcmu-26-27/shuna-backend/blob/main/app.py) (Bottle application), [`captcha.py`](https://github.com/bsitcmu-26-27/shuna-backend/blob/main/captcha.py) (Turnstile verification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_api["Bottle application<br/>[app.py]"]
  node_post_api["Post endpoints<br/>[main.py]"]
end

subgraph group_content["Post Processing"]
  node_captcha["Turnstile verification<br/>[captcha.py]"]
  node_image["Image compression<br/>[image_compress.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

subgraph group_persistence["Persistence"]
  node_storage["Image storage helper<br/>[storage.py]"]
  node_postgres[("Post database")]
  node_s3[("S3 object storage")]
end

subgraph group_admin["Administration"]
  node_admin_routes["Admin page route<br/>[admin.py]"]
  node_admin_page["Admin page template<br/>[index.html]"]
end

node_visitor(("Visitor"))
node_administrator(("Administrator"))
node_turnstile["Cloudflare Turnstile"]

node_visitor -->|"sends requests"| node_api
node_api -->|"dispatches routes"| node_post_api
node_post_api -->|"checks submissions"| node_captcha
node_captcha -->|"reads secret"| node_config
node_captcha -->|"verifies token"| node_turnstile
node_post_api -->|"compresses upload"| node_image
node_post_api -->|"uploads image"| node_storage
node_storage -->|"writes object"| node_s3
node_post_api -->|"reads and writes posts"| node_postgres
node_post_api -->|"builds image URL"| node_storage
node_administrator -->|"requests admin"| node_api
node_api -->|"dispatches route"| node_admin_routes
node_admin_routes -->|"reads template"| node_admin_page
node_admin_routes -->|"reads backend URL"| node_config
node_admin_routes -->|"serves page"| node_administrator
node_post_api -->|"returns post data"| node_visitor

click node_api "https://github.com/bsitcmu-26-27/shuna-backend/blob/main/app.py"
click node_post_api "https://github.com/bsitcmu-26-27/shuna-backend/blob/main/main.py"
click node_captcha "https://github.com/bsitcmu-26-27/shuna-backend/blob/main/captcha.py"
click node_image "https://github.com/bsitcmu-26-27/shuna-backend/blob/main/image_compress.py"
click node_storage "https://github.com/bsitcmu-26-27/shuna-backend/blob/main/storage.py"
click node_admin_routes "https://github.com/bsitcmu-26-27/shuna-backend/blob/main/routes/admin.py"
click node_admin_page "https://github.com/bsitcmu-26-27/shuna-backend/blob/main/index.html"
click node_config "https://github.com/bsitcmu-26-27/shuna-backend/blob/main/config.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_api,node_post_api toneBlue
class node_captcha,node_image,node_config toneAmber
class node_storage,node_postgres,node_s3 toneMint
class node_admin_routes,node_admin_page toneRose
class node_visitor,node_administrator,node_turnstile toneIndigo
```

## Components

### HTTP API

- [Bottle application](https://github.com/bsitcmu-26-27/shuna-backend/blob/main/app.py): `app.py`
- [Post endpoints](https://github.com/bsitcmu-26-27/shuna-backend/blob/main/main.py): `main.py`

### Post Processing

- [Turnstile verification](https://github.com/bsitcmu-26-27/shuna-backend/blob/main/captcha.py): `captcha.py`
- [Image compression](https://github.com/bsitcmu-26-27/shuna-backend/blob/main/image_compress.py): `image_compress.py`
- [Runtime configuration](https://github.com/bsitcmu-26-27/shuna-backend/blob/main/config.py): `config.py`

### Persistence

- [Image storage helper](https://github.com/bsitcmu-26-27/shuna-backend/blob/main/storage.py): `storage.py`
- **Post database**
- **S3 object storage**

### Administration

- [Admin page route](https://github.com/bsitcmu-26-27/shuna-backend/blob/main/routes/admin.py): `routes/admin.py`
- [Admin page template](https://github.com/bsitcmu-26-27/shuna-backend/blob/main/index.html): `index.html`

### Other components

- **Visitor**
- **Administrator**
- **Cloudflare Turnstile**

## Connections

- Visitor → Bottle application: sends requests
- Bottle application → Post endpoints: dispatches routes
- Post endpoints → Turnstile verification: checks submissions
- Turnstile verification → Runtime configuration: reads secret
- Turnstile verification → Cloudflare Turnstile: verifies token
- Post endpoints → Image compression: compresses upload
- Post endpoints → Image storage helper: uploads image
- Image storage helper → S3 object storage: writes object
- Post endpoints → Post database: reads and writes posts
- Post endpoints → Image storage helper: builds image URL
- Administrator → Bottle application: requests admin
- Bottle application → Admin page route: dispatches route
- Admin page route → Admin page template: reads template
- Admin page route → Runtime configuration: reads backend URL
- Admin page route → Administrator: serves page
- Post endpoints → Visitor: returns post data