# krol-x/elysia-vue-spa-template architecture

> Architecture diagram of the GitHub repository krol-x/elysia-vue-spa-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/krol-x/elysia-vue-spa-template
- Repository: https://github.com/krol-x/elysia-vue-spa-template

## Overview

#### Purpose and Runtime

A Bun-based full-stack SPA template: Vue/Vite provides the browser UI, while an Elysia API serves application endpoints and, in production, the built SPA. Development runs frontend and backend together; production targets a compiled server plus static assets.

Key entry points: `bin/dev.ts`, `app/api/src/index.ts`, `app/api/src/server.ts`, and `app/web/src/main.ts`.

#### Backend Application Host

The API is organized around an Elysia server and modular route registration. `app/api/src/index.ts` is the backend process entry, while `app/api/src/server.ts` likely assembles API routes, health endpoints, middleware, and static SPA serving for the production full-app runtime.

`app/api/build.ts` is the API build boundary; resulting artifacts are intended to be run by Bun.

#### Domain Modules: Authentication and Users

Backend business capabilities are split into feature modules with explicit routing, controllers, services, DTOs, and user persistence models:

- Authentication: `app/api/src/module/auth/routes.ts`, `app/api/src/module/auth/controller.ts`, `app/api/src/module/auth/service.ts`
- User management: `app/api/src/module/user/routes.ts`, `app/api/src/module/user/controller.ts`, `app/api/src/module/user/service.ts`
- User data model/contracts: `app/api/src/module/user/model.ts`, `app/api/src/module/user/dto.ts`

The expected request flow is Elysia route → controller → service → database, with DTOs defining API input/output boundaries.

#### Database and Lifecycle Operations

Drizzle manages relational database schema and migration state. The database integration boundary is `app/api/src/db.ts` and `app/api/src/config/database.ts`. Schema evolution is represented by checked-in migrations, beginning with `app/api/drizzle/0000_new_giant_girl.sql`.

Operational database commands are separate executable paths: `app/api/bin/migrate.ts` applies migrations and `app/api/bin/seed.ts` populates initial data. This keeps application startup distinct from schema deployment and data initialization.

#### Frontend SPA

Vue bootstraps from `app/web/src/main.ts` into the root shell `app/web/src/App.vue`. Client-side navigation is defined in `app/web/src/router/index.ts`.

The UI centers on authentication-aware and user/dashboard views: `app/web/src/composables/useAuth.ts`, `app/web/src/components/AuthModal.vue`, `app/web/src/components/Dashboard.vue`, and `app/web/src/components/Users.vue`. Modal components provide interaction boundaries for authentication, profiles, and user actions.

#### Frontend–API Boundary

In development, Vite hosts the SPA and proxies API calls, allowing browser access through port 5173 while the API can also run directly on port 3000. `app/web/vite.config.ts` defines this dev-server integration boundary.

In production, the backend serves both static frontend output and `/api` endpoints on one host (documented as port 3030). The health endpoint `/api/up` is the basic process/API availability probe.

#### Shared Contracts and Build Orchestration

`app/shared/index.ts` is the intended cross-package contract location for types or utilities used by both API and web packages. Package-level manifests at `app/api/package.json`, `app/web/package.json`, and `app/shared/package.json` establish the workspace boundaries.

Root scripts coordinate the system: `bin/dev.ts` orchestrates development, while root build commands produce the deployable API and SPA artifacts.

Main entry points: [`app/api/src/server.ts`](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/src/server.ts) (Elysia server), [`app/api/src/db.ts`](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/src/db.ts) (Drizzle database), [`app/api/src/module/user/controller.ts`](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/src/module/user/controller.ts) (User controller), [`app/web/src/App.vue`](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/web/src/App.vue) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["API service"]
  node_api_entry{{"API process entry<br/>Bun entry<br/>[index.ts]"}}
  node_api_server["Elysia server<br/>application host<br/>[server.ts]"]
  node_auth_routes["Auth routes<br/>route module<br/>[routes.ts]"]
  node_auth_controller["Auth controller<br/>[controller.ts]"]
  node_auth_service["Auth service<br/>[service.ts]"]
  node_user_routes["User routes<br/>route module<br/>[routes.ts]"]
  node_user_controller["User controller<br/>[controller.ts]"]
  node_user_service["User service<br/>[service.ts]"]
  node_user_contracts["User models and DTOs<br/>API contracts<br/>[dto.ts]"]
  node_api_build{{"API build<br/>build boundary<br/>[build.ts]"}}
end

subgraph group_frontend["Vue SPA"]
  node_web_main{{"Vue bootstrap<br/>SPA entry<br/>[main.ts]"}}
  node_app_shell["App shell<br/>Vue root<br/>[App.vue]"]
  node_router["Client router<br/>Vue router<br/>[index.ts]"]
  node_auth_ui["Auth UI state<br/>composable and modal<br/>[useAuth.ts]"]
  node_dashboard["Dashboard and users UI<br/>Vue views<br/>[Dashboard.vue]"]
  node_vite["Vite dev host<br/>development server<br/>[vite.config.ts]"]
end

subgraph group_data["Database operations"]
  node_db[("Drizzle database<br/>database integration<br/>[db.ts]")]
  node_migrations["Schema migrations<br/>SQL migrations"]
  node_migrate{{"Migration command<br/>Bun script<br/>[migrate.ts]"}}
  node_seed{{"Seed command<br/>Bun script<br/>[seed.ts]"}}
end

node_dev{{"Development orchestrator<br/>Bun script<br/>[dev.ts]"}}
node_shared["Shared contracts<br/>workspace package<br/>[index.ts]"]

node_dev -->|"starts API"| node_api_entry
node_dev -->|"starts web dev"| node_vite
node_api_entry -->|"boots"| node_api_server
node_api_server -->|"registers"| node_auth_routes
node_api_server -->|"registers"| node_user_routes
node_auth_routes -->|"dispatches"| node_auth_controller
node_auth_controller -->|"calls"| node_auth_service
node_user_routes -->|"dispatches"| node_user_controller
node_user_controller -->|"calls"| node_user_service
node_user_controller -->|"validates with"| node_user_contracts
node_user_service -->|"persists"| node_db
node_auth_service -->|"accesses"| node_db
node_migrate -->|"applies"| node_migrations
node_migrate -->|"updates schema"| node_db
node_seed -->|"populates"| node_db
node_web_main -->|"mounts"| node_app_shell
node_app_shell -->|"uses"| node_router
node_app_shell -->|"uses"| node_auth_ui
node_router -->|"navigates to"| node_dashboard
node_vite -.->|"proxies /api"| node_api_server
node_auth_ui -.->|"API requests"| node_api_server
node_dashboard -.->|"API requests"| node_api_server
node_api_server -.->|"serves built SPA"| node_web_main
node_api_build -->|"compiles"| node_api_entry
node_shared -.->|"shared by"| node_api_server
node_shared -.->|"shared by"| node_web_main

click node_dev "https://github.com/krol-x/elysia-vue-spa-template/blob/main/bin/dev.ts"
click node_api_entry "https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/src/index.ts"
click node_api_server "https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/src/server.ts"
click node_auth_routes "https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/src/module/auth/routes.ts"
click node_auth_controller "https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/src/module/auth/controller.ts"
click node_auth_service "https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/src/module/auth/service.ts"
click node_user_routes "https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/src/module/user/routes.ts"
click node_user_controller "https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/src/module/user/controller.ts"
click node_user_service "https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/src/module/user/service.ts"
click node_user_contracts "https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/src/module/user/dto.ts"
click node_db "https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/src/db.ts"
click node_migrations "https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/drizzle/0000_new_giant_girl.sql"
click node_migrate "https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/bin/migrate.ts"
click node_seed "https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/bin/seed.ts"
click node_web_main "https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/web/src/main.ts"
click node_app_shell "https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/web/src/App.vue"
click node_router "https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/web/src/router/index.ts"
click node_auth_ui "https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/web/src/composables/useAuth.ts"
click node_dashboard "https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/web/src/components/Dashboard.vue"
click node_vite "https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/web/vite.config.ts"
click node_shared "https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/shared/index.ts"
click node_api_build "https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/build.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_entry,node_api_server,node_auth_routes,node_auth_controller,node_auth_service,node_user_routes,node_user_controller,node_user_service,node_user_contracts,node_api_build toneBlue
class node_web_main,node_app_shell,node_router,node_auth_ui,node_dashboard,node_vite toneAmber
class node_db,node_migrations,node_migrate,node_seed toneMint
class node_dev,node_shared toneNeutral
```

## Components

### API service

Bun/Elysia application and domain modules.

- [API process entry](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/src/index.ts): Bun entry · `app/api/src/index.ts`
- [Elysia server](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/src/server.ts): application host · Registers endpoints and serves the SPA in production. · `app/api/src/server.ts`
- [Auth routes](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/src/module/auth/routes.ts): route module · `app/api/src/module/auth/routes.ts`
- [Auth controller](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/src/module/auth/controller.ts): controller · `app/api/src/module/auth/controller.ts`
- [Auth service](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/src/module/auth/service.ts): service · `app/api/src/module/auth/service.ts`
- [User routes](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/src/module/user/routes.ts): route module · `app/api/src/module/user/routes.ts`
- [User controller](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/src/module/user/controller.ts): controller · `app/api/src/module/user/controller.ts`
- [User service](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/src/module/user/service.ts): service · `app/api/src/module/user/service.ts`
- [User models and DTOs](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/src/module/user/dto.ts): API contracts · Defines user persistence and request/response boundaries. · `app/api/src/module/user/dto.ts`
- [API build](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/build.ts): build boundary · Produces Bun-run server artifacts. · `app/api/build.ts`

### Vue SPA

Browser application and development host.

- [Vue bootstrap](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/web/src/main.ts): SPA entry · `app/web/src/main.ts`
- [App shell](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/web/src/App.vue): Vue root · `app/web/src/App.vue`
- [Client router](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/web/src/router/index.ts): Vue router · `app/web/src/router/index.ts`
- [Auth UI state](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/web/src/composables/useAuth.ts): composable and modal · Authentication-aware browser interaction boundary. · `app/web/src/composables/useAuth.ts`
- [Dashboard and users UI](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/web/src/components/Dashboard.vue): Vue views · `app/web/src/components/Dashboard.vue`
- [Vite dev host](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/web/vite.config.ts): development server · Hosts the SPA and proxies API calls during development. · `app/web/vite.config.ts`

### Database operations

Drizzle schema, migrations, and lifecycle commands.

- [Drizzle database](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/src/db.ts): database integration · `app/api/src/db.ts`
- [Schema migrations](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/drizzle/0000_new_giant_girl.sql): SQL migrations · `app/api/drizzle/0000_new_giant_girl.sql`
- [Migration command](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/bin/migrate.ts): Bun script · `app/api/bin/migrate.ts`
- [Seed command](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/api/bin/seed.ts): Bun script · `app/api/bin/seed.ts`

### Other components

- [Development orchestrator](https://github.com/krol-x/elysia-vue-spa-template/blob/main/bin/dev.ts): Bun script · Runs frontend and backend together. · `bin/dev.ts`
- [Shared contracts](https://github.com/krol-x/elysia-vue-spa-template/blob/main/app/shared/index.ts): workspace package · Cross-package types and utilities. · `app/shared/index.ts`

## Connections

- Development orchestrator → API process entry: starts API
- Development orchestrator → Vite dev host: starts web dev
- API process entry → Elysia server: boots
- Elysia server → Auth routes: registers
- Elysia server → User routes: registers
- Auth routes → Auth controller: dispatches
- Auth controller → Auth service: calls
- User routes → User controller: dispatches
- User controller → User service: calls
- User controller → User models and DTOs: validates with
- User service → Drizzle database: persists
- Auth service → Drizzle database: accesses
- Migration command → Schema migrations: applies
- Migration command → Drizzle database: updates schema
- Seed command → Drizzle database: populates
- Vue bootstrap → App shell: mounts
- App shell → Client router: uses
- App shell → Auth UI state: uses
- Client router → Dashboard and users UI: navigates to
- Vite dev host → Elysia server: proxies /api
- Auth UI state → Elysia server: API requests
- Dashboard and users UI → Elysia server: API requests
- Elysia server → Vue bootstrap: serves built SPA
- API build → API process entry: compiles
- Shared contracts → Elysia server: shared by
- Shared contracts → Vue bootstrap: shared by