> For the complete documentation index, see [llms.txt](https://voyzu.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://voyzu.gitbook.io/docs/extending-voyzu/architecture.md).

# Architecture

Voyzu is an Open Source, modern web application serving two functions:

* A Financial Ledger
* A modular Rapid Application Development (RAD) Framework

## Database

A single PostgreSQL database holds all application data. For more information see [Data Patterns](/docs/extending-voyzu/patterns/data.md)

## Application Layers

The application architecture uses a small number of layers, each layer (represented by a folder) contains files with the same architectural purpose. Below is the high level directory structure and purpose description.

### `/apps`

* Contains runnable Next.js applications and reference apps.
* `apps/web` is the main Voyzu web application used by end users.
* `apps/api-reference` hosts the API reference guide
* `apps/ui-reference` hosts the shared UI reference guide including shared generic React components.
* `apps/generated-files` stores generated artifacts used by API reference application.

### `/docs`

* Contains project documentation, public guides and extension guidance.
* `docs/public` is published to the public documentation site.

### `/infra`

* Contains infrastructure files that support the application runtime.
* `infra/db/schema` stores database schema scripts for core tables, domains and triggers.
* `infra/db/temp` stores temporary or transitional database scripts.
* `infra/extensions` is reserved for application extension infrastructure.

### `/packages`

* Contains shared Voyzu workspace packages under `packages/@voyzu`.

The below packages ship with Voyzu:

#### `@voyzu/api`

* Functions that support general API routing behaviour. I.e. generic API support functions, not the API routes themselves

#### `@voyzu/api-reference`

* Powers the NextJS API reference application (`http:localhost:3002` by default)

#### `@voyzu/capability`

* Provides shared runtime capabilities such as database access, HTTP helpers, export and PDF support.
* Holds cross-module backend services that are not specific to one business module.
* Keeps infrastructure-facing code behind stable package exports.

#### `@voyzu/external-integration`

* Contains integration-specific code for services outside the Voyzu application boundary.
* Keeps external service concerns separate from core modules and UI packages.
* Currently includes the `fx-rate` integration area for foreign exchange rate functionality.

#### `@voyzu/modules`

* Contains all Voyzu business functionality, both back end and front end

#### `@voyzu/types`

* Defines shared TypeScript contracts used across apps, modules and API boundaries.
* Contains DTOs, parameter types, error types and module-specific data shapes.

#### `@voyzu/ui-components`

* Provides reusable React controls for navigation, forms, data display and interaction patterns.
* Builds on layout and style packages for consistent behavior and appearance.
* Showcased in the the `ui-reference` NextJS application (`http://localhost:3001` by default)

#### `@voyzu/ui-layout`

* Provides shared layout CSS, CSS modules and responsive breakpoint helpers.
* Encodes reusable page layouts for list, detail, create and report surfaces.
* Keeps layout structure separate from business modules and visual styling.

#### `@voyzu/ui-style`

* Provides global design tokens, reset CSS, typography and shared CSS modules.
* Defines foundational visual language used by apps and UI packages.
* Should be used for common styling primitives such as colors, spacing and form styles.

#### `@voyzu/ui-surface`

* Powers the Application rendering shell.

### `/scripts`

* Contains developer, operational and generation scripts.
* `scripts/api-docs` generates API operation documentation and OpenAPI output.
* `scripts/db` contains database setup, seed, sample data and utility scripts.
* `scripts/extensions` is reserved for application extensions.

## Developing a new module

The best way to learn more about Voyzu architecture and its Rapid Application Development (RAD) capabilities is to develop a new module. See [Add a new module](/docs/extending-voyzu/add-a-new-module.md)