How Archery Applications Work

Archery separates application startup from request handling. Startup builds the services the application needs; the HTTP pipeline then reuses those services for each incoming request.

Application startup

A typical application starts in this order:

Create the application

App() provides the central application object and service container.

Load configuration

AppConfig.create() reads JSON configuration files and is usually bound as an eager singleton.

Providers bind services, migrations, clients, seeders, or other application capabilities.

Boot the application

app.boot() prepares framework services, initializes eager bindings, and runs provider boot work.

Resolve runtime services

After boot, resolve services such as Router and StaticFilesServer from the container.

final app = App();
final config = await AppConfig.create();

app.container.singleton<AppConfig>(
  factory: (_, [_]) => config,
  eager: true,
);

app.registerGroup('migrations', [
  SqliteMigrationsProvider(),
]);

await app.boot();

A provider’s register() phase defines bindings. Its boot() phase performs work that may depend on bindings from other providers.

Request lifecycle

For each incoming request:

HttpServer yields a HttpRequest.
StaticFilesServer.tryServe() handles matching public assets.
AppKernel.handle() prepares the request and invokes global middleware.
Router.dispatch() matches an exact or typed dynamic route.
Route middleware runs in its defined order.
The route handler writes a JSON, text, view, redirect, file, or error response.
Unmatched requests receive the framework’s 404 response.

Component responsibilities

Component	Responsibility
`App`	Coordinates registration, boot hooks, application state, and shutdown
`ServiceContainer`	Registers and resolves application services
`Provider`	Packages service registration and startup work
`AppKernel`	Starts the request pipeline and global middleware
`Router`	Matches methods and paths, then invokes route middleware and handlers
`FormRequest`	Exposes cached query, body, and uploaded-file input
`TemplateEngine`	Renders server-side templates
`Model`	Provides persistence operations across configured database drivers

Failure and shutdown

A startup or listener failure should be logged and followed by explicit resource cleanup. Close the HTTP server and external clients, call app.container.dispose() when you rely on container disposal callbacks, and then call app.shutdown() to update the application lifecycle.

try {
  // Bind and run the server.
} catch (error, stack) {
  app.archeryLogger.error('Application error', {
    'error': error.toString(),
    'stack': stack.toString(),
  });
  await app.container.dispose();
  await app.shutdown();
}

Service container

Learn how Archery owns and resolves services.

Build a small app

Apply the request lifecycle in a working JSON API.

Getting Started

HTTP Layer

Application Core

Data And Security

How Archery Applications Work

Application startup

Request lifecycle

Component responsibilities

Failure and shutdown

Service container

Build a small app

​Application startup

​Request lifecycle

​Component responsibilities

​Failure and shutdown

Service container

Build a small app

Application startup

Request lifecycle

Component responsibilities

Failure and shutdown