# shubh-14-cloud/tether architecture

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

- Interactive diagram: https://gitdiagram.com/shubh-14-cloud/tether
- Repository: https://github.com/shubh-14-cloud/tether

## Overview

1. **Overall shape**
   - Tether is a small Java web application packaged as a WAR and deployed to Apache Tomcat 10.1.
   - The architecture is centered on one real-time server-side endpoint plus one database access component, with a thin browser-based client.

2. **Client layer**
   - The user interface lives in `src/main/webapp` as `index.html` and `index.jsp`.
   - This is a vanilla HTML/CSS/JavaScript front end, so the browser handles rendering, user input, and WebSocket communication directly rather than going through a separate frontend framework or API server.

3. **Web runtime boundary**
   - `WEB-INF/web.xml` defines the web application configuration and wiring expected by the servlet container.
   - Tomcat is the execution environment for HTTP entry points and the WebSocket endpoint, which means the app depends on container-managed deployment rather than an embedded server.

4. **Real-time messaging subsystem**
   - `src/main/java/com/chat/ChatWebSocket.java` is the core application service.
   - It is the WebSocket endpoint responsible for live chat traffic, including the real-time features described in the README: rooms, direct messages, typing indicators, and emoji reactions.
   - This class is the main boundary between browser clients and server-side chat state.

5. **Persistence subsystem**
   - `src/main/java/com/chat/DatabaseManager.java` is the data-access and schema-management layer.
   - It connects the chat logic to MySQL, handles persistence of chat history, and likely performs startup initialization because the README says tables are created automatically on first launch.
   - `schema_v2.sql` is the canonical schema definition for the MySQL database and indicates that schema evolution is managed outside the request path.

6. **Data flow**
   - Browser clients connect to the server over WebSocket.
   - Chat events enter `ChatWebSocket`, which then reads/writes persistent state through `DatabaseManager`.
   - Updates are broadcast back to connected clients in real time, while message history and other durable state are stored in MySQL.

7. **State model**
   - The app supports both transient and persistent state.
   - Transient state includes live connections, typing status, and in-memory coordination for active rooms/users.
   - Persistent state includes message history and room/user records stored in MySQL.

8. **Deployment and environment**
   - The repository includes a `Dockerfile` and `docker-entrypoint.sh`, showing the app is designed to run in a containerized deployment.
   - Railway is the documented hosting target, with MySQL provided as a separate service and configuration injected through environment variables.

9. **Configuration boundary**
   - Database credentials are externalized via `DB_URL`, `DB_USER`, and `DB_PASS`.
   - This keeps the application portable across local Tomcat, Docker, and Railway deployments without code changes.

10. **Build and packaging**
   - Maven (`pom.xml`) builds the application into `target/Tether.war`.
   - The packaged WAR includes runtime dependencies such as the MySQL JDBC driver and a JSON library, which supports server-side parsing/serialization of chat payloads.

11. **Operational dependencies**
   - MySQL 8 is a required external service and is not embedded.
   - Tomcat 10.1 is the servlet/WebSocket container, so the app’s network-facing behavior is constrained by Jakarta WebSocket and servlet container semantics.

12. **Architecture summary for diagramming**
   - Draw three major boxes: browser client, Tomcat-hosted Java WebSocket backend, and MySQL database.
   - Show WebSocket traffic between browser and `ChatWebSocket`, and JDBC-backed persistence between `ChatWebSocket`/`DatabaseManager` and MySQL.
   - Treat `web.xml`, `schema_v2.sql`, Docker files, and environment variables as supporting configuration/infrastructure rather than primary business logic.

Main entry points: [`src/main/java/com/chat/ChatWebSocket.java`](https://github.com/shubh-14-cloud/tether/blob/main/src/main/java/com/chat/ChatWebSocket.java) (Chat WebSocket), [`src/main/java/com/chat/DatabaseManager.java`](https://github.com/shubh-14-cloud/tether/blob/main/src/main/java/com/chat/DatabaseManager.java) (Database Manager), [`target/Tether.war`](https://github.com/shubh-14-cloud/tether/blob/main/target/Tether.war) (Tether WAR), [`src/main/webapp/index.html`](https://github.com/shubh-14-cloud/tether/blob/main/src/main/webapp/index.html) (Browser UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_browser_ui["Browser UI<br/>vanilla frontend<br/>[index.html]"]
  node_jsp_view["JSP View<br/>server page<br/>[index.jsp]"]
end

subgraph group_server["Server"]
  node_web_xml["Web Config<br/>servlet config<br/>[web.xml]"]
  node_chat_ws["Chat WebSocket<br/>endpoint<br/>[ChatWebSocket.java]"]
  node_db_manager["Database Manager<br/>data access"]
  node_tomcat["Tomcat 10.1<br/>servlet container"]
  node_war_build["WAR Build<br/>maven package<br/>[pom.xml]"]
  node_dockerfile["Dockerfile<br/>container build"]
  node_entrypoint["Entrypoint<br/>startup script"]
  node_env_cfg["Env Vars<br/>runtime config<br/>[.env.example]"]
  node_war_artifact["Tether WAR<br/>deployed app<br/>[Tether.war]"]
  node_runtime_libs["Runtime JARs<br/>bundled deps"]
end

subgraph group_data["Data"]
  node_mysql[("MySQL<br/>database")]
  node_schema_sql["Schema SQL<br/>schema definition<br/>[schema_v2.sql]"]
end

node_browser_ui -->|"HTTP/WebSocket"| node_tomcat
node_jsp_view -->|"HTTP"| node_tomcat
node_tomcat -->|"loads"| node_web_xml
node_tomcat -->|"hosts"| node_chat_ws
node_web_xml -->|"wires"| node_chat_ws
node_chat_ws -->|"uses"| node_db_manager
node_db_manager -->|"JDBC"| node_mysql
node_schema_sql -->|"initializes"| node_mysql
node_chat_ws -.->|"persists"| node_mysql
node_chat_ws -->|"broadcasts"| node_browser_ui
node_war_build -->|"packages"| node_war_artifact
node_war_artifact -->|"deploys to"| node_tomcat
node_dockerfile -->|"ships"| node_war_artifact
node_entrypoint -.->|"starts"| node_dockerfile
node_env_cfg -->|"configures"| node_db_manager
node_runtime_libs -.->|"supports"| node_chat_ws

click node_browser_ui "https://github.com/shubh-14-cloud/tether/blob/main/src/main/webapp/index.html"
click node_jsp_view "https://github.com/shubh-14-cloud/tether/blob/main/src/main/webapp/index.jsp"
click node_web_xml "https://github.com/shubh-14-cloud/tether/blob/main/src/main/webapp/WEB-INF/web.xml"
click node_chat_ws "https://github.com/shubh-14-cloud/tether/blob/main/src/main/java/com/chat/ChatWebSocket.java"
click node_db_manager "https://github.com/shubh-14-cloud/tether/blob/main/src/main/java/com/chat/DatabaseManager.java"
click node_war_build "https://github.com/shubh-14-cloud/tether/blob/main/pom.xml"
click node_dockerfile "https://github.com/shubh-14-cloud/tether/tree/main/Dockerfile"
click node_entrypoint "https://github.com/shubh-14-cloud/tether/blob/main/docker-entrypoint.sh"
click node_env_cfg "https://github.com/shubh-14-cloud/tether/blob/main/.env.example"
click node_schema_sql "https://github.com/shubh-14-cloud/tether/blob/main/schema_v2.sql"
click node_war_artifact "https://github.com/shubh-14-cloud/tether/blob/main/target/Tether.war"
click node_runtime_libs "https://github.com/shubh-14-cloud/tether/blob/main/target/Tether/WEB-INF/lib/mysql-connector-j-8.3.0.jar"

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_browser_ui,node_jsp_view toneBlue
class node_web_xml,node_chat_ws,node_db_manager,node_tomcat,node_war_build,node_dockerfile,node_entrypoint,node_env_cfg,node_war_artifact,node_runtime_libs toneAmber
class node_mysql,node_schema_sql toneMint
```

## Components

### Client

Browser-facing UI and runtime interaction

- [Browser UI](https://github.com/shubh-14-cloud/tether/blob/main/src/main/webapp/index.html): vanilla frontend · HTML/CSS/JS client rendered in the browser · `src/main/webapp/index.html`
- [JSP View](https://github.com/shubh-14-cloud/tether/blob/main/src/main/webapp/index.jsp): server page · Secondary web entry served by the container · `src/main/webapp/index.jsp`

### Server

Tomcat-hosted web and WebSocket runtime

- [Web Config](https://github.com/shubh-14-cloud/tether/blob/main/src/main/webapp/WEB-INF/web.xml): servlet config · Container wiring and deployment descriptor · `src/main/webapp/WEB-INF/web.xml`
- [Chat WebSocket](https://github.com/shubh-14-cloud/tether/blob/main/src/main/java/com/chat/ChatWebSocket.java): endpoint · Real-time chat endpoint handling rooms, DMs, typing, and reactions · `src/main/java/com/chat/ChatWebSocket.java`
- [Database Manager](https://github.com/shubh-14-cloud/tether/blob/main/src/main/java/com/chat/DatabaseManager.java): data access · JDBC persistence and schema initialization layer · `src/main/java/com/chat/DatabaseManager.java`
- **Tomcat 10.1**: servlet container · External runtime hosting HTTP and WebSocket entry points
- [WAR Build](https://github.com/shubh-14-cloud/tether/blob/main/pom.xml): maven package · Builds the deployable web archive · `pom.xml`
- [Dockerfile](https://github.com/shubh-14-cloud/tether/tree/main/Dockerfile): container build · Container image definition for deployment · `Dockerfile`
- [Entrypoint](https://github.com/shubh-14-cloud/tether/blob/main/docker-entrypoint.sh): startup script · Container startup and launch wiring · `docker-entrypoint.sh`
- [Env Vars](https://github.com/shubh-14-cloud/tether/blob/main/.env.example): runtime config · Externalized database credentials and deployment settings · `.env.example`
- [Tether WAR](https://github.com/shubh-14-cloud/tether/blob/main/target/Tether.war): deployed app · Packaged application artifact deployed to the container · `target/Tether.war`
- [Runtime JARs](https://github.com/shubh-14-cloud/tether/blob/main/target/Tether/WEB-INF/lib/mysql-connector-j-8.3.0.jar): bundled deps · Packaged JDBC and JSON libraries included in the WAR · `target/Tether/WEB-INF/lib/mysql-connector-j-8.3.0.jar`

### Data

Persistent storage and schema

- **MySQL**: database · External persistent store for chat history and records
- [Schema SQL](https://github.com/shubh-14-cloud/tether/blob/main/schema_v2.sql): schema definition · Canonical MySQL schema for initial database setup · `schema_v2.sql`

## Connections

- Browser UI → Tomcat 10.1: HTTP/WebSocket · Browser connects to the container-hosted app
- JSP View → Tomcat 10.1: HTTP · Container serves the JSP entry point
- Tomcat 10.1 → Web Config: loads · Servlet container reads deployment configuration
- Tomcat 10.1 → Chat WebSocket: hosts · WebSocket endpoint runs inside Tomcat
- Web Config → Chat WebSocket: wires · Deployment descriptor binds the endpoint
- Chat WebSocket → Database Manager: uses · Chat logic delegates persistence and initialization
- Database Manager → MySQL: JDBC · Reads and writes durable chat state
- Schema SQL → MySQL: initializes · Schema defines the database structure
- Chat WebSocket → MySQL: persists · Live events are stored durably through the data layer
- Chat WebSocket → Browser UI: broadcasts · Real-time updates are pushed back to connected clients
- WAR Build → Tether WAR: packages · Maven produces the deployable WAR
- Tether WAR → Tomcat 10.1: deploys to · WAR is deployed into the servlet container
- Dockerfile → Tether WAR: ships · Container image includes the packaged app
- Entrypoint → Dockerfile: starts · Container startup script launches the app
- Env Vars → Database Manager: configures · Database connection settings are injected externally
- Runtime JARs → Chat WebSocket: supports · Bundled libraries provide JSON and JDBC support
