# bmdyy/tudo architecture

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

- Interactive diagram: https://gitdiagram.com/bmdyy/tudo
- Repository: https://github.com/bmdyy/tudo

## Overview

1. **What this repository is**
   TUDO is a deliberately vulnerable PHP application packaged for local training. The runtime is split into containerized services, with the web app, PostgreSQL database, and an admin/cron-emulation component managed by Docker Compose.

2. **Top-level deployment shape**
   `docker-compose.yaml` is the orchestrator. The main user-facing service serves the PHP app from `app/`, while a separate PostgreSQL container holds application state. A third container under `docker/admin` emulates periodic administrator activity, which matters because some app state changes are driven on a schedule rather than only by interactive user requests.

3. **Web application entry points**
   The public HTTP surface is in `app/`:
   - `index.php` as the landing page
   - `login.php` for authentication
   - `profile.php` for authenticated user data
   - `forgotusername.php`, `forgotpassword.php`, `resetpassword.php` for account recovery
   - `admin/` for privileged actions
   This is a classic server-rendered PHP app, not a SPA.

4. **Shared application layer**
   Common behavior is centralized in `app/includes/`:
   - `db_connect.php` for PostgreSQL access
   - `utils.php` for helper logic
   - `header.php` and `login_footer.php` for shared page chrome
   - `logout.php` for session teardown
   - `createpost.php` for creating user content
   This folder is the main boundary between page controllers and backend logic.

5. **Template/rendering subsystem**
   `app/templates/` and `app/templates_c/` indicate Smarty-style templating. `motd.tpl` is a dedicated template for the message-of-the-day UI, and `templates_c/` is the compiled-template cache/output directory. This means some page content is rendered through a template engine rather than raw PHP echo statements.

6. **Persistent data model**
   The README exposes the primary database tables:
   - `users` for accounts and role data
   - `tokens` for authentication or reset-related tokens
   - `class_posts` for user-generated posts/content
   - `motd_images` for images used by the message-of-the-day/admin content
   These tables support the main flows: login, recovery, posting, and admin content management.

7. **Authentication and account recovery flow**
   Login and recovery pages likely coordinate through the `users` and `tokens` tables, with sessions maintained in PHP. The application supports standard credentials for two normal users and one admin, but the app is designed so that access can also be reached through alternate recovery/auth paths.

8. **User content flow**
   Authenticated users can create posts via `includes/createpost.php`, and those posts are persisted in `class_posts`. `profile.php` likely reads user identity plus recent or related content back from the database to display account state and posts.

9. **Admin subsystem**
   `app/admin/` contains privileged endpoints:
   - `import_user.php`
   - `update_motd.php`
   - `upload_image.php`
   These represent the administrative control plane for importing users, changing the MOTD, and managing images. The admin area is separate from the normal user-facing pages but still part of the same PHP app.

10. **Scheduled/admin automation**
    The `docker/admin/emulate.cron` and `docker/admin/emulate.py` files indicate a cron-like background process that simulates admin actions every minute. This is an important architectural boundary: some privileged state transitions happen asynchronously, outside direct browser interaction.

11. **Infrastructure and runtime dependencies**
    `docker/app/Dockerfile`, `docker/admin/Dockerfile`, `docker/init.sql`, and `app/vendor/` show that the app is containerized and bootstrapped with an initial schema/data load. `app/.htaccess` and `app/templates/.htaccess` are used to control Apache-accessible paths and likely protect sensitive directories from direct web access.

12. **Operational/debug tooling**
    The repo is set up for local reverse debugging with Xdebug and VS Code (`.vscode/`, `docker/app/xdebug.ini`). The README also notes PostgreSQL query logging via the database container logs, which is useful for tracing request-to-SQL data flow during analysis.

13. **Non-runtime content**
    `solutions/` contains exploit PoCs and writeups, and `screenshots/` contains documentation assets. These are not part of the live application architecture, but they explain intended challenge paths and should be excluded from the runtime diagram.

14. **High-level data flow**
    Browser requests enter the PHP app container, which renders pages and delegates state changes to shared include code. That code reads/writes PostgreSQL. Admin-specific state can also be modified by the scheduled emulation service. Static assets and templates stay within the app container, while compiled templates and uploaded images act as filesystem-backed working data alongside the database.

Main entry points: [`app/includes/db_connect.php`](https://github.com/bmdyy/tudo/blob/main/app/includes/db_connect.php) (Shared Logic), [`docker/app/Dockerfile`](https://github.com/bmdyy/tudo/tree/main/docker/app/Dockerfile) (App Image), [`docker-compose.yaml`](https://github.com/bmdyy/tudo/blob/main/docker-compose.yaml) (Compose), [`docker/init.sql`](https://github.com/bmdyy/tudo/blob/main/docker/init.sql) (Database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deployment["Deployment"]
  node_compose["Compose<br/>orchestrator"]
  node_app_image["App Image<br/>php-apache"]
  node_db_image[("Postgres<br/>database<br/>[init.sql]")]
  node_admin_image["Admin Image<br/>worker"]
end

subgraph group_webapp["Web App"]
  node_index["Home<br/>page<br/>[index.php]"]
  node_login["Login<br/>auth page<br/>[login.php]"]
  node_profile["Profile<br/>account page<br/>[profile.php]"]
  node_recovery["Recovery<br/>[forgotpassword.php]"]
  node_reset["Reset<br/>recovery page<br/>[resetpassword.php]"]
  node_admin_ui["Admin UI<br/>privileged pages<br/>[import_user.php]"]
  node_shared["Shared Logic<br/>php includes<br/>[db_connect.php]"]
  node_templates["Templates<br/>smarty views<br/>[motd.tpl]"]
end

subgraph group_adminsvc["Admin Automation"]
  node_cron_emu["Cron Emu<br/>scheduled worker<br/>[emulate.cron]"]
  node_emu_script["Emulator<br/>python job<br/>[emulate.py]"]
end

subgraph group_data["Data"]
  node_db[("Database<br/>postgres data<br/>[init.sql]")]
  node_images["Images<br/>filesystem assets"]
  node_vendor["Vendor<br/>php deps"]
end

node_compose -->|"builds"| node_app_image
node_compose -->|"starts"| node_db_image
node_compose -->|"starts"| node_admin_image
node_app_image -->|"serves"| node_index
node_app_image -->|"includes"| node_shared
node_app_image -->|"renders"| node_templates
node_app_image -->|"stores"| node_images
node_shared -->|"queries"| node_db
node_login -->|"auth via"| node_shared
node_profile -->|"loads"| node_shared
node_recovery -->|"uses"| node_shared
node_reset -->|"uses"| node_shared
node_admin_ui -->|"admin via"| node_shared
node_shared -->|"depends on"| node_vendor
node_db_image -->|"initializes"| node_db
node_admin_image -->|"runs"| node_cron_emu
node_cron_emu -->|"invokes"| node_emu_script
node_emu_script -->|"modifies"| node_db
node_admin_ui -->|"uploads"| node_images
node_templates -.->|"feeds"| node_index

click node_compose "https://github.com/bmdyy/tudo/blob/main/docker-compose.yaml"
click node_app_image "https://github.com/bmdyy/tudo/tree/main/docker/app/Dockerfile"
click node_db_image "https://github.com/bmdyy/tudo/blob/main/docker/init.sql"
click node_admin_image "https://github.com/bmdyy/tudo/tree/main/docker/admin/Dockerfile"
click node_cron_emu "https://github.com/bmdyy/tudo/blob/main/docker/admin/emulate.cron"
click node_emu_script "https://github.com/bmdyy/tudo/blob/main/docker/admin/emulate.py"
click node_index "https://github.com/bmdyy/tudo/blob/main/app/index.php"
click node_login "https://github.com/bmdyy/tudo/blob/main/app/login.php"
click node_profile "https://github.com/bmdyy/tudo/blob/main/app/profile.php"
click node_recovery "https://github.com/bmdyy/tudo/blob/main/app/forgotpassword.php"
click node_reset "https://github.com/bmdyy/tudo/blob/main/app/resetpassword.php"
click node_admin_ui "https://github.com/bmdyy/tudo/blob/main/app/admin/import_user.php"
click node_shared "https://github.com/bmdyy/tudo/blob/main/app/includes/db_connect.php"
click node_templates "https://github.com/bmdyy/tudo/blob/main/app/templates/motd.tpl"
click node_db "https://github.com/bmdyy/tudo/blob/main/docker/init.sql"
click node_images "https://github.com/bmdyy/tudo/tree/main/app/images"
click node_vendor "https://github.com/bmdyy/tudo/tree/main/app/vendor"

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_compose,node_app_image,node_db_image,node_admin_image toneBlue
class node_index,node_login,node_profile,node_recovery,node_reset,node_admin_ui,node_shared,node_templates toneAmber
class node_cron_emu,node_emu_script toneMint
class node_db,node_images,node_vendor toneRose
```

## Components

### Deployment

Containerized runtime and bootstrapping

- [Compose](https://github.com/bmdyy/tudo/blob/main/docker-compose.yaml): orchestrator · Starts and wires the application, database, and admin services · `docker-compose.yaml`
- [App Image](https://github.com/bmdyy/tudo/tree/main/docker/app/Dockerfile): php-apache · Container image for the main PHP web application · `docker/app/Dockerfile`
- [Postgres](https://github.com/bmdyy/tudo/blob/main/docker/init.sql): database · PostgreSQL service and initial schema/data load · `docker/init.sql`
- [Admin Image](https://github.com/bmdyy/tudo/tree/main/docker/admin/Dockerfile): worker · Container image for scheduled admin emulation · `docker/admin/Dockerfile`

### Web App

Server-rendered PHP application

- [Home](https://github.com/bmdyy/tudo/blob/main/app/index.php): page · Landing page · `app/index.php`
- [Login](https://github.com/bmdyy/tudo/blob/main/app/login.php): auth page · Authentication entry point · `app/login.php`
- [Profile](https://github.com/bmdyy/tudo/blob/main/app/profile.php): account page · Authenticated user view · `app/profile.php`
- [Recovery](https://github.com/bmdyy/tudo/blob/main/app/forgotpassword.php): account recovery · Username and password recovery pages · `app/forgotpassword.php`
- [Reset](https://github.com/bmdyy/tudo/blob/main/app/resetpassword.php): recovery page · Password reset entry point · `app/resetpassword.php`
- [Admin UI](https://github.com/bmdyy/tudo/blob/main/app/admin/import_user.php): privileged pages · Privileged HTTP endpoints for user import, MOTD, and image upload · `app/admin/import_user.php`
- [Shared Logic](https://github.com/bmdyy/tudo/blob/main/app/includes/db_connect.php): php includes · Common DB, session, utility, and post creation code · `app/includes/db_connect.php`
- [Templates](https://github.com/bmdyy/tudo/blob/main/app/templates/motd.tpl): smarty views · Smarty-style templates and compiled cache · `app/templates/motd.tpl`

### Admin Automation

Privileged background activity

- [Cron Emu](https://github.com/bmdyy/tudo/blob/main/docker/admin/emulate.cron): scheduled worker · Minute-based admin activity emulator · `docker/admin/emulate.cron`
- [Emulator](https://github.com/bmdyy/tudo/blob/main/docker/admin/emulate.py): python job · Script that performs automated admin actions · `docker/admin/emulate.py`

### Data

Persistent and filesystem-backed state

- [Database](https://github.com/bmdyy/tudo/blob/main/docker/init.sql): postgres data · Users, tokens, posts, and MOTD image tables · `docker/init.sql`
- [Images](https://github.com/bmdyy/tudo/tree/main/app/images): filesystem assets · Uploaded and served image content · `app/images`
- [Vendor](https://github.com/bmdyy/tudo/tree/main/app/vendor): php deps · Bundled PHP dependencies · `app/vendor`

## Connections

- Compose → App Image: builds · Defines the main web service image
- Compose → Postgres: starts · Runs PostgreSQL as a separate service
- Compose → Admin Image: starts · Runs the admin emulation service
- App Image → Home: serves · Hosts the public PHP entry points
- App Image → Shared Logic: includes · Page controllers rely on shared backend logic
- App Image → Templates: renders · Uses template views for selected output
- App Image → Images: stores · Uses filesystem-backed image content
- Shared Logic → Database: queries · Reads and writes application state in PostgreSQL
- Login → Shared Logic: auth via · Delegates authentication and session handling
- Profile → Shared Logic: loads · Fetches account state and related content
- Recovery → Shared Logic: uses · Coordinates account recovery flows
- Reset → Shared Logic: uses · Applies password reset logic
- Admin UI → Shared Logic: admin via · Privileged actions reuse shared backend code
- Shared Logic → Vendor: depends on · Relies on bundled PHP libraries
- Postgres → Database: initializes · Bootstraps schema and seed data
- Admin Image → Cron Emu: runs · Container executes the scheduled emulator
- Cron Emu → Emulator: invokes · Cron entry launches the Python worker
- Emulator → Database: modifies · Performs automated privileged state changes
- Admin UI → Images: uploads · Admin endpoints manage image assets
- Templates → Home: feeds · Template content contributes to rendered pages
