# phoccy/the-polyglot-workspace architecture

> Architecture diagram of the GitHub repository phoccy/the-polyglot-workspace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/phoccy/the-polyglot-workspace
- Repository: https://github.com/phoccy/the-polyglot-workspace

## Overview

1. **Repository purpose**
   - This is a polyglot sandbox demonstrating the same todo-style frontend being powered by one of four interchangeable backend implementations, all talking to the same SQLite database file.

2. **Top-level split**
   - The repo is divided into two major runtime boundaries:
     - `Frontend/`: a static client application.
     - `Backends/`: four separate server implementations in different languages.
   - There is also a shared `Database/` concept in the README, but it is not tracked in the tree and is auto-created locally as `todo.db`.

3. **Frontend subsystem**
   - `Frontend/index.html`, `assets/css/styles.css`, and `assets/js/app.js` form a single-page style vanilla web client.
   - The frontend is intentionally backend-agnostic: it should work unchanged against any backend as long as the API contract remains consistent.

4. **Client-to-server interaction**
   - The browser loads the static HTML/CSS/JS from the frontend folder.
   - The JavaScript layer is the active integration point: it issues HTTP requests to `localhost:8000` and renders the backend response.
   - The frontend does not appear to own any persistence; it is a pure consumer of the API.

5. **Shared API contract**
   - All four backends are designed to expose the same routes and payload shape.
   - This is the key architectural boundary: the UI depends on the contract, not on language-specific implementation details.
   - The README emphasizes that a backend can be stopped and replaced by another without changing the frontend.

6. **SQLite persistence layer**
   - All backends use the same SQLite database file as the storage source.
   - The database is local and file-based, which makes backend swapping possible without provisioning an external database service.
   - The shared DB is the cross-runtime state boundary in the system.

7. **PHP backend**
   - `Backends/01-PHP/` is a standalone PHP server implementation.
   - The presence of `index.php`, `router.php`, and `config.php` suggests a lightweight routed API built around PHP’s built-in server and PDO for SQLite access.
   - This backend is one possible API provider for the frontend.

8. **Python backend**
   - `Backends/02-Python/server.py` is a minimal Python server, likely built directly on the standard library `http.server`.
   - It uses Python’s built-in SQLite support, making it another self-contained API host with minimal framework dependency.

9. **C# backend**
   - `Backends/03-CSharp/Program.cs` with a `.csproj` indicates a .NET console/service-style HTTP server.
   - The README notes `HttpListener` and `Microsoft.Data.Sqlite`, so this backend is an asynchronous listener that maps request data to C# models before hitting SQLite.

10. **Java backend**
   - `Backends/04-Java/src/com/todoapi/Server.java` is a raw Java server using the JDK `HttpServer`.
   - The README notes JDBC plus custom regex parsing, which implies the Java version performs its own route/parameter handling rather than relying on a higher-level web framework.

11. **Port and deployment model**
   - Every backend is intended to listen on port `8000`.
   - Only one backend is meant to be active at a time, since they all occupy the same port and serve the same API shape.
   - The architecture is therefore “single frontend + swappable backend runtime,” not a clustered or federated system.

12. **Operational boundaries**
   - Each backend directory is an isolated execution environment with its own runtime toolchain:
     - PHP runtime
     - Python runtime
     - .NET runtime
     - JDK + SQLite JDBC dependencies
   - This isolation is important for the diagram because the implementations are independent, but they converge on the same client contract and database file.

13. **What to show in an architecture diagram**
   - A good diagram would center on three layers:
     - Browser/frontend
     - One of four backend implementations
     - Shared SQLite database
   - The critical visual idea is replaceability: the frontend connects to whichever backend is currently running, while the database remains the common persistence anchor.

Main entry points: [`Frontend/assets/js/app.js`](https://github.com/phoccy/the-polyglot-workspace/blob/main/Frontend/assets/js/app.js) (API client), [`Backends/01-PHP/index.php`](https://github.com/phoccy/the-polyglot-workspace/blob/main/Backends/01-PHP/index.php) (PHP API), [`Backends/02-Python/server.py`](https://github.com/phoccy/the-polyglot-workspace/blob/main/Backends/02-Python/server.py) (Python API), [`Backends/03-CSharp/Program.cs`](https://github.com/phoccy/the-polyglot-workspace/blob/main/Backends/03-CSharp/Program.cs) (C# API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_html["HTML shell<br/>static entry<br/>[index.html]"]
  node_frontend_css["Styles<br/>ui styling<br/>[styles.css]"]
  node_frontend_js["API client<br/>browser logic<br/>[app.js]"]
end

subgraph group_backends["Backends"]
  node_backend_php["PHP API<br/>php server<br/>[index.php]"]
  node_backend_py["Python API<br/>python server<br/>[server.py]"]
  node_backend_cs["C# API<br/>dotnet server<br/>[Program.cs]"]
  node_backend_java["Java API<br/>java server<br/>[Server.java]"]
end

subgraph group_data["Data"]
  node_sqlite_db[("todo.db<br/>sqlite file")]
end

node_api_contract{{"API contract<br/>shared routes"}}

node_frontend_html -->|"loads"| node_frontend_css
node_frontend_html -->|"loads"| node_frontend_js
node_frontend_js -->|"uses"| node_api_contract
node_frontend_js -->|"requests"| node_backend_php
node_frontend_js -->|"requests"| node_backend_py
node_frontend_js -->|"requests"| node_backend_cs
node_frontend_js -->|"requests"| node_backend_java
node_backend_php -->|"implements"| node_api_contract
node_backend_py -->|"implements"| node_api_contract
node_backend_cs -->|"implements"| node_api_contract
node_backend_java -->|"implements"| node_api_contract
node_backend_php -->|"reads/writes"| node_sqlite_db
node_backend_py -->|"reads/writes"| node_sqlite_db
node_backend_cs -->|"reads/writes"| node_sqlite_db
node_backend_java -->|"reads/writes"| node_sqlite_db

click node_frontend_html "https://github.com/phoccy/the-polyglot-workspace/blob/main/Frontend/index.html"
click node_frontend_css "https://github.com/phoccy/the-polyglot-workspace/blob/main/Frontend/assets/css/styles.css"
click node_frontend_js "https://github.com/phoccy/the-polyglot-workspace/blob/main/Frontend/assets/js/app.js"
click node_backend_php "https://github.com/phoccy/the-polyglot-workspace/blob/main/Backends/01-PHP/index.php"
click node_backend_py "https://github.com/phoccy/the-polyglot-workspace/blob/main/Backends/02-Python/server.py"
click node_backend_cs "https://github.com/phoccy/the-polyglot-workspace/blob/main/Backends/03-CSharp/Program.cs"
click node_backend_java "https://github.com/phoccy/the-polyglot-workspace/blob/main/Backends/04-Java/src/com/todoapi/Server.java"

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_frontend_html,node_frontend_css,node_frontend_js toneBlue
class node_backend_php,node_backend_py,node_backend_cs,node_backend_java toneAmber
class node_sqlite_db toneMint
class node_api_contract toneNeutral
```

## Components

### Frontend

Static client application

- [HTML shell](https://github.com/phoccy/the-polyglot-workspace/blob/main/Frontend/index.html): static entry · Loads the single-page client · `Frontend/index.html`
- [Styles](https://github.com/phoccy/the-polyglot-workspace/blob/main/Frontend/assets/css/styles.css): ui styling · Presentation layer for the client · `Frontend/assets/css/styles.css`
- [API client](https://github.com/phoccy/the-polyglot-workspace/blob/main/Frontend/assets/js/app.js): browser logic · Fetches data from the active backend and renders it · `Frontend/assets/js/app.js`

### Backends

Four interchangeable API servers

- [PHP API](https://github.com/phoccy/the-polyglot-workspace/blob/main/Backends/01-PHP/index.php): php server · Standalone PHP implementation of the todo API · `Backends/01-PHP/index.php`
- [Python API](https://github.com/phoccy/the-polyglot-workspace/blob/main/Backends/02-Python/server.py): python server · Minimal Python implementation of the todo API · `Backends/02-Python/server.py`
- [C# API](https://github.com/phoccy/the-polyglot-workspace/blob/main/Backends/03-CSharp/Program.cs): dotnet server · .NET HTTP listener implementation of the todo API · `Backends/03-CSharp/Program.cs`
- [Java API](https://github.com/phoccy/the-polyglot-workspace/blob/main/Backends/04-Java/src/com/todoapi/Server.java): java server · JDK HttpServer implementation of the todo API · `Backends/04-Java/src/com/todoapi/Server.java`

### Data

Shared SQLite persistence

- **todo.db**: sqlite file · Shared local database used by every backend

### Other components

- **API contract**: shared routes · Common request and response shape shared by all backends

## Connections

- HTML shell → Styles: loads · HTML references the stylesheet
- HTML shell → API client: loads · HTML boots the client script
- API client → API contract: uses · Client depends on the shared HTTP contract
- API client → PHP API: requests · Can talk to the PHP backend when it is active
- API client → Python API: requests · Can talk to the Python backend when it is active
- API client → C# API: requests · Can talk to the C# backend when it is active
- API client → Java API: requests · Can talk to the Java backend when it is active
- PHP API → API contract: implements · PHP server exposes the shared routes
- Python API → API contract: implements · Python server exposes the shared routes
- C# API → API contract: implements · C# server exposes the shared routes
- Java API → API contract: implements · Java server exposes the shared routes
- PHP API → todo.db: reads/writes · PHP backend persists to the shared SQLite file
- Python API → todo.db: reads/writes · Python backend persists to the shared SQLite file
- C# API → todo.db: reads/writes · C# backend persists to the shared SQLite file
- Java API → todo.db: reads/writes · Java backend persists to the shared SQLite file