H
Harpia

Project Structure

The Harpia App structure is built for developers who need a scalable, maintainable foundation. It follows a Modular Monolith pattern, ensuring that your infrastructure remains separate from your business logic.

my-app/
├── app/             # Global Infrastructure
├── modules/         # Domain-driven Features
├── prisma/          # Database Schema & Migrations
├── start/           # Bootstrapping & Initializers
├── .env             # Environment Configuration
└── package.json     # Project Manifest

Global Infrastructure (/app)

The app directory serves as the backbone of your project. It houses the logic required to run the framework’s systems across all features.

config

Centralized application settings, environment mapping, and external service credentials.

database

Connection managers, seeders, and model factories for your data persistence layer.

middlewares

Global request interceptors for security (CORS, Auth), logging, and telemetry.

observers

Event listeners that react to system-wide signals or database lifecycle hooks.

services

Infrastructure-level singletons such as Mailers, S3 Storage, and Third-party APIs.

tasks

Definition of background jobs and cron-scheduled processes powered by the Harpia runner.

Domain Modules (/modules)

Business logic is organized by Domains inside the modules directory. Each folder represents a unique feature or bounded context of your application.

Harpia encourages encapsulation: a module should contain everything it needs to function, from routes to its internal services.

modules/
└── user/
    ├── controllers/   # Route handlers
    ├── services/      # Domain-specific logic
    ├── repositories/  # Data access layer
    ├── validations/   # Zod schema definitions
    ├── tests/         # Module-specific testing
    └── user.routes.ts # Route entry point

Lifecycle & Data

The root contains the essential files that handle how your application starts and how it interacts with your database.

prisma

The source of truth for your database schema, enums, and migrations.

start

Bootstrapping logic executed before the server starts listening for requests.

.env

Local environment secrets. Harpia automatically loads these into the Bun environment.