Initial project scaffold

Set up MVC architecture with front controller, router, autoloader,
database singleton, and Docker Compose stack (Nginx + PHP-FPM + MariaDB).
Includes DB schema, responsive layout, dev tooling (php-cs-fixer,
parallel-lint), and documentation.

1 files changed, 116 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4bea6c5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,116 @@
+# Camagru
+
+A web application for creating and sharing photos with superposable overlays. Users can capture images via webcam (or upload), apply overlay effects, and share them in a public gallery with likes and comments.
+
+## Features
+
+- **User accounts** — Register, email verification, login, password reset, profile editing
+- **Photo editor** — Webcam capture or image upload with selectable overlay images (PNG with alpha), server-side compositing
+- **Gallery** — Public paginated feed of all creations, likes and comments for logged-in users
+- **Notifications** — Email notification when someone comments on your image (configurable)
+- **Responsive** — Mobile-friendly layout
+
+## Stack
+
+| Component | Technology |
+|-----------|------------|
+| Backend | PHP 8.5 (standard library only) |
+| Frontend | HTML / CSS / JavaScript |
+| Database | MariaDB 10.11 |
+| Web server | Nginx 1.27 |
+| Containers | Docker Compose |
+
+## Getting started
+
+```sh
+# 1. Clone the repository
+git clone <repo-url> && cd camagru
+
+# 2. Create your environment file
+cp .env.example .env
+# Edit .env with your own values
+
+# 3. Install dev tools
+composer install
+
+# 4. Build and run
+docker-compose up --build
+
+# 5. Open in browser
+# http://localhost:8080
+```
+
+## Host setup (Manjaro)
+
+`phpactor` (LSP) requires the `iconv` extension. Install and enable it:
+
+```sh
+pamac install php85-iconv
+sudo sed -i 's/;extension=iconv/extension=iconv/' /etc/php/php.ini
+```
+
+## Note on composer.json
+
+This project does not use Composer for runtime dependencies — only the PHP standard library is used. The `composer.json` exists to satisfy dev tooling:
+
+- `php-cs-fixer` — code style formatting (requires `composer.json` to determine target PHP version)
+- `php-parallel-lint` — syntax checking (dev dependency)
+
+These are development tools only and are not part of the application code.
+
+## Linting
+
+```sh
+vendor/bin/parallel-lint src/
+```
+
+## PHP architecture
+
+This project follows standard PHP patterns commonly used in framework-less applications:
+
+### Front controller
+
+All HTTP requests are routed by Nginx to a single file: `src/public/index.php`. This file bootstraps the app and delegates to the router. No other PHP file is directly accessible from the web.
+
+### Namespaces and autoloading
+
+PHP namespaces organize classes into a hierarchy (like directories). `namespace App\Controllers;` means the class lives under `App\Controllers`. The `use` keyword imports a class so you can refer to it by its short name instead of the full path (e.g. `Database` instead of `\App\Database`).
+
+The autoloader in `bootstrap.php` uses `spl_autoload_register` to automatically `require` class files when they're first used. It maps the `App\` namespace prefix to the `src/app/` directory, so `App\Controllers\HomeController` loads from `src/app/Controllers/HomeController.php`.
+
+### MVC pattern
+
+- **Models** (`src/app/Models/`) — Data access layer, each model wraps a database table and uses prepared statements via PDO
+- **Views** (`src/app/Views/`) — PHP templates that output HTML. A layout file (`layouts/main.php`) wraps page-specific content via an `include`. View files have variables that appear undefined — this is because they are `include`d by controllers and inherit all variables from the calling scope (e.g. `$dbStatus` defined in `HomeController::index()` is available in the view it includes)
+- **Controllers** (`src/app/Controllers/`) — Handle requests, call models, and render views
+
+### Request lifecycle
+
+1. Nginx receives request, forwards to `public/index.php`
+2. `bootstrap.php` starts the session, loads `.env`, registers the autoloader
+3. Routes are defined in `config/routes.php` (mapping URL patterns to controller methods)
+4. `Router::dispatch()` matches the URL against registered patterns and calls the matching controller method
+5. The controller fetches data via models and renders a view inside the layout
+
+## Image format choices
+
+- **Overlays** are PNG (alpha channel required for transparency)
+- **User input** (webcam captures, uploads) may be JPEG or PNG — GD is compiled with JPEG support to handle both
+- **Final composited images** are saved as PNG to preserve overlay transparency
+
+## Project structure
+
+```
+camagru/
+├── docker-compose.yml
+├── .env.example
+├── docker/
+│   ├── nginx/          # Nginx Dockerfile and config
+│   ├── php/            # PHP-FPM Dockerfile (GD + PDO)
+│   └── mariadb/        # Database init script
+└── src/
+    ├── public/         # Document root (entry point, CSS, JS, assets)
+    ├── app/            # Application code (Controllers, Models, Views)
+    ├── config/         # Route definitions
+    └── uploads/        # User-generated images
+```