# Architecture

VeloFrame is designed for clarity, modularity, and speed. Here’s how the main parts fit together:

---

## Project Structure
```
pages/                 # Page controllers (handle requests)
templates/             # HTML templates
templates/components/  # Reusable HTML components
VeloFrame/             # Core framework code
index.php              # Main entry point
.htaccess              # URL rewriting
```

---

## Core Flow
1. **Request**: All requests are routed to `index.php` (via `.htaccess`).
2. **Server**: `VeloFrame/Server.php` handles routing and serves the correct page/controller.
3. **Routing**: `RoutingHandler` maps URIs to controllers (auto-discovered if enabled).
4. **Controller**: Controllers in `pages/` process the request and prepare data.
5. **Template**: The controller loads a template, sets variables, and renders HTML.
6. **Components**: Templates can include reusable components for DRY code.
7. **Response**: Optimized HTML, CSS, JS, and images are served to the client.

---

## Key Classes
- `Server`: Bootstraps the app, discovers pages, serves requests.
- `RoutingHandler`: Maps URIs to controllers.
- `DefaultPageController` / `RequestHandler`: Base classes for your controllers.
- `Template`: Loads and renders HTML templates with variables.
- `TemplateComponent`: Handles reusable HTML blocks.
- `Optimizer`: (Optional) Minifies and optimizes assets.

---

## Extending VeloFrame
- Add new controllers in `pages/`.
- Create new templates/components in `templates/`.
- Extend core classes in `VeloFrame/` for advanced use.

See [API Reference](./API-Reference.md) for details on each class.