# Architecture

Quaeriva is a lightweight PHP 8 application in a Mini-MVC shape. It is deliberately not a framework application.

## The stack

| Layer | Choice |
|---|---|
| Language | PHP 8.1+ |
| Database | MySQL/MariaDB, InnoDB, `utf8mb4` |
| Data access | PDO with prepared statements |
| Views | Server-rendered PHP templates |
| Client | Vanilla JavaScript, no build step |
| Styling | CSS custom properties, logical properties, local webfonts |
| Content | Markdown stored, safe HTML rendered server-side |
| Config | Database-backed settings plus environment files |

No Composer, npm, Redis, queue, WebSocket or cron is required at runtime.

## Directory map

```
app/
├── Admin/          admin repositories, dashboard, editorial seeding
├── Auth/           registration, verification, sign-in, recovery
├── Community/      comments, follows, spam risk, posting policy
├── Content/        Markdown to safe HTML
├── Database/       connection, migrator
├── Http/           JSON API router, controllers, serializers
├── Mailer/         mailer factory and transports
├── Notifications/  notification service and channels
├── Questions/      question and answer services
├── Seo/            SEO builder, canonical policy, sitemap service
├── Settings/       settings repository
├── Security/       CSRF, rate limits, bot guard, challenge
├── Support/        hooks, logger, translator, locale, helpers
├── Theme/          theme manager, tokens, presets, profiles
├── Users/          profiles, trust
├── Widgets/        widget registry and renderer
└── views/          server-rendered templates
admin/              admin front controller
api/v1/             API entry point
public/             web root, front controller, assets, themes
database/migrations forward-only SQL migrations
resources/lang/     ar.php and en.php
```

## Design rules

**One source tree for every environment.** Local and production run the same files. Only `.env`, `config/database.local.php` and `config/site.local.php` differ.

**The admin path is a setting, not a folder.** Every admin URL is generated by a helper.

**The base path is a setting.** The application runs at `/`, `/ask`, or any subdirectory without template edits.

**Markdown in, safe HTML out.** Arbitrary user HTML is never stored.

**The filesystem is the trust boundary for code.** Themes and plugins are installed over the filesystem; nothing executable is uploaded through the browser.

**Behaviour first, structure second.** Regression coverage precedes refactoring. Controllers are being extracted from the front controllers one at a time, with no behaviour change inside an extraction.

## Request entry points

| Entry | Handles |
|---|---|
| `public/index.php` | Every public page, plus sitemap and robots |
| `admin/index.php` | The admin panel, reached through the configured path |
| `api/v1/index.php` | The JSON API |
| `install/` | First-run installer, disabled after installation |

See [Request lifecycle](REQUEST-LIFECYCLE.md).

## Extension points

Filesystem plugins register handlers on a small documented hook catalog. Themes override views and supply tokens. Both are isolated: a failure is logged and contained.

See [Hooks and events](HOOKS-EVENTS.md).
