# lifeforge-app/lifeforge architecture

> Architecture diagram of the GitHub repository lifeforge-app/lifeforge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lifeforge-app/lifeforge
- Repository: https://github.com/lifeforge-app/lifeforge

## Overview

LifeForge is a self-hosted personal management system whose extensible modules provide productivity, finance, lifestyle, and learning features. A user enters through the web client; authentication and module availability determine the routes presented, while the API handles requests and exposes core services. The repository also includes account security, personalization, backups, and API-key management. The graph highlights documented product areas and sampled runtime relationships; some feature internals are represented by their exact source directories because their implementation was not excerpted.

Main entry points: [`apps/api/src/core/routes/core.routes.ts`](https://github.com/lifeforge-app/lifeforge/blob/main/apps/api/src/core/routes/core.routes.ts) (Core API routes), [`apps/web/src/core/routing/hooks/useAppRouter.ts`](https://github.com/lifeforge-app/lifeforge/blob/main/apps/web/src/core/routing/hooks/useAppRouter.ts) (App routing), [`apps/web/src/core/routing/utils/routerFactory.tsx`](https://github.com/lifeforge-app/lifeforge/blob/main/apps/web/src/core/routing/utils/routerFactory.tsx) (Route factory), [`apps/api/src/lib/auth`](https://github.com/lifeforge-app/lifeforge/tree/main/apps/api/src/lib/auth) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Web client<br/>[index.tsx]"]
  node_router["App routing<br/>[useAppRouter.ts]"]
  node_routerconfig["Route factory<br/>[routerFactory.tsx]"]
  node_routebuilder["Module routes<br/>[routeBuilder.tsx]"]
  node_dashboard["Dashboard"]
  node_personalization["Personalization"]
end

subgraph group_modules["Module platform"]
  node_federation["Module federation"]
  node_moduleloader["Server module loader"]
  node_metadata["Module metadata"]
end

subgraph group_api["API services"]
  node_apiapp["API application<br/>[app.ts]"]
  node_coreapi["Core API routes<br/>[core.routes.ts]"]
  node_controller["Route controller<br/>[controllerLogic.ts]"]
  node_requestutils["Request processing<br/>[parsePayload.ts]"]
  node_response["Response handling<br/>[response.ts]"]
  node_database[("Database services")]
  node_fonts["Font services"]
  node_ai["AI services"]
  node_userstore["User services"]
end

subgraph group_identity["Identity and settings"]
  node_auth["Authentication"]
  node_accountsettings["Account settings"]
  node_apikeys["API keys"]
  node_backups["Backups"]
end

node_user(("User"))
node_localstore[("Self-hosted server")]

node_user -->|"uses"| node_webapp
node_webapp -.->|"starts"| node_router
node_router -->|"reads modules"| node_federation
node_router -->|"checks session"| node_auth
node_router -->|"builds routes"| node_routerconfig
node_routerconfig -->|"creates routes"| node_routebuilder
node_routerconfig -->|"redirects to"| node_dashboard
node_federation -.->|"provides modules"| node_router
node_moduleloader -->|"gathers metadata"| node_metadata
node_user -->|"manages life"| node_dashboard
node_user -.->|"customizes experience"| node_personalization
node_user -.->|"manages account"| node_accountsettings
node_apiapp -->|"mounts routes"| node_coreapi
node_coreapi -->|"routes to"| node_auth
node_coreapi -->|"routes to"| node_database
node_coreapi -->|"routes to"| node_userstore
node_coreapi -->|"routes to"| node_apikeys
node_coreapi -->|"routes to"| node_fonts
node_coreapi -->|"routes to"| node_ai
node_controller -->|"parses payload"| node_requestutils
node_controller -->|"sends response"| node_response
node_user -->|"controls data"| node_localstore
node_backups -.->|"backs up data"| node_localstore
node_accountsettings -.->|"configures security"| node_auth

click node_webapp "https://github.com/lifeforge-app/lifeforge/blob/main/apps/web/src/index.tsx"
click node_router "https://github.com/lifeforge-app/lifeforge/blob/main/apps/web/src/core/routing/hooks/useAppRouter.ts"
click node_routerconfig "https://github.com/lifeforge-app/lifeforge/blob/main/apps/web/src/core/routing/utils/routerFactory.tsx"
click node_routebuilder "https://github.com/lifeforge-app/lifeforge/blob/main/apps/web/src/core/routing/utils/routeBuilder.tsx"
click node_dashboard "https://github.com/lifeforge-app/lifeforge/tree/main/apps/web/src/system/dashboard"
click node_personalization "https://github.com/lifeforge-app/lifeforge/tree/main/apps/web/src/system/personalization"
click node_federation "https://github.com/lifeforge-app/lifeforge/blob/main/packages/federation/src/providers/FederationProvider.tsx"
click node_moduleloader "https://github.com/lifeforge-app/lifeforge/blob/main/apps/api/src/core/functions/modules/loadAndRegisterModuleRoutes.ts"
click node_metadata "https://github.com/lifeforge-app/lifeforge/blob/main/apps/api/src/core/functions/modules/gatherModuleMetadata.ts"
click node_apiapp "https://github.com/lifeforge-app/lifeforge/blob/main/apps/api/src/core/app.ts"
click node_coreapi "https://github.com/lifeforge-app/lifeforge/blob/main/apps/api/src/core/routes/core.routes.ts"
click node_controller "https://github.com/lifeforge-app/lifeforge/blob/main/apps/api/src/core/functions/routes/functions/controllerLogic.ts"
click node_requestutils "https://github.com/lifeforge-app/lifeforge/blob/main/apps/api/src/core/functions/routes/utils/parsePayload.ts"
click node_response "https://github.com/lifeforge-app/lifeforge/blob/main/apps/api/src/core/functions/routes/utils/response.ts"
click node_database "https://github.com/lifeforge-app/lifeforge/tree/main/apps/api/src/lib/database"
click node_auth "https://github.com/lifeforge-app/lifeforge/tree/main/apps/api/src/lib/auth"
click node_accountsettings "https://github.com/lifeforge-app/lifeforge/tree/main/apps/web/src/system/accountSettings"
click node_apikeys "https://github.com/lifeforge-app/lifeforge/tree/main/apps/api/src/lib/apiKeys"
click node_backups "https://github.com/lifeforge-app/lifeforge/tree/main/apps/api/src/lib/backups"
click node_fonts "https://github.com/lifeforge-app/lifeforge/tree/main/apps/api/src/lib/fonts"
click node_ai "https://github.com/lifeforge-app/lifeforge/tree/main/apps/api/src/lib/ai"
click node_userstore "https://github.com/lifeforge-app/lifeforge/tree/main/apps/api/src/lib/user"

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_webapp,node_router,node_routerconfig,node_routebuilder,node_dashboard,node_personalization,node_user toneBlue
class node_federation,node_moduleloader,node_metadata,node_localstore toneAmber
class node_apiapp,node_coreapi,node_controller,node_requestutils,node_response,node_database,node_fonts,node_ai,node_userstore toneMint
class node_auth,node_accountsettings,node_apikeys,node_backups toneRose
```

## Components

### Web experience

- [Web client](https://github.com/lifeforge-app/lifeforge/blob/main/apps/web/src/index.tsx): `apps/web/src/index.tsx`
- [App routing](https://github.com/lifeforge-app/lifeforge/blob/main/apps/web/src/core/routing/hooks/useAppRouter.ts): `apps/web/src/core/routing/hooks/useAppRouter.ts`
- [Route factory](https://github.com/lifeforge-app/lifeforge/blob/main/apps/web/src/core/routing/utils/routerFactory.tsx): `apps/web/src/core/routing/utils/routerFactory.tsx`
- [Module routes](https://github.com/lifeforge-app/lifeforge/blob/main/apps/web/src/core/routing/utils/routeBuilder.tsx): `apps/web/src/core/routing/utils/routeBuilder.tsx`
- [Dashboard](https://github.com/lifeforge-app/lifeforge/tree/main/apps/web/src/system/dashboard): `apps/web/src/system/dashboard`
- [Personalization](https://github.com/lifeforge-app/lifeforge/tree/main/apps/web/src/system/personalization): `apps/web/src/system/personalization`

### Module platform

- [Module federation](https://github.com/lifeforge-app/lifeforge/blob/main/packages/federation/src/providers/FederationProvider.tsx): `packages/federation/src/providers/FederationProvider.tsx`
- [Server module loader](https://github.com/lifeforge-app/lifeforge/blob/main/apps/api/src/core/functions/modules/loadAndRegisterModuleRoutes.ts): `apps/api/src/core/functions/modules/loadAndRegisterModuleRoutes.ts`
- [Module metadata](https://github.com/lifeforge-app/lifeforge/blob/main/apps/api/src/core/functions/modules/gatherModuleMetadata.ts): `apps/api/src/core/functions/modules/gatherModuleMetadata.ts`

### API services

- [API application](https://github.com/lifeforge-app/lifeforge/blob/main/apps/api/src/core/app.ts): `apps/api/src/core/app.ts`
- [Core API routes](https://github.com/lifeforge-app/lifeforge/blob/main/apps/api/src/core/routes/core.routes.ts): `apps/api/src/core/routes/core.routes.ts`
- [Route controller](https://github.com/lifeforge-app/lifeforge/blob/main/apps/api/src/core/functions/routes/functions/controllerLogic.ts): `apps/api/src/core/functions/routes/functions/controllerLogic.ts`
- [Request processing](https://github.com/lifeforge-app/lifeforge/blob/main/apps/api/src/core/functions/routes/utils/parsePayload.ts): `apps/api/src/core/functions/routes/utils/parsePayload.ts`
- [Response handling](https://github.com/lifeforge-app/lifeforge/blob/main/apps/api/src/core/functions/routes/utils/response.ts): `apps/api/src/core/functions/routes/utils/response.ts`
- [Database services](https://github.com/lifeforge-app/lifeforge/tree/main/apps/api/src/lib/database): `apps/api/src/lib/database`
- [Font services](https://github.com/lifeforge-app/lifeforge/tree/main/apps/api/src/lib/fonts): `apps/api/src/lib/fonts`
- [AI services](https://github.com/lifeforge-app/lifeforge/tree/main/apps/api/src/lib/ai): `apps/api/src/lib/ai`
- [User services](https://github.com/lifeforge-app/lifeforge/tree/main/apps/api/src/lib/user): `apps/api/src/lib/user`

### Identity and settings

- [Authentication](https://github.com/lifeforge-app/lifeforge/tree/main/apps/api/src/lib/auth): `apps/api/src/lib/auth`
- [Account settings](https://github.com/lifeforge-app/lifeforge/tree/main/apps/web/src/system/accountSettings): `apps/web/src/system/accountSettings`
- [API keys](https://github.com/lifeforge-app/lifeforge/tree/main/apps/api/src/lib/apiKeys): `apps/api/src/lib/apiKeys`
- [Backups](https://github.com/lifeforge-app/lifeforge/tree/main/apps/api/src/lib/backups): `apps/api/src/lib/backups`

### Other components

- **User**
- **Self-hosted server**

## Connections

- User → Web client: uses (evidence: `README.md`)
- Web client → App routing: starts
- App routing → Module federation: reads modules (evidence: `apps/web/src/core/routing/hooks/useAppRouter.ts`)
- App routing → Authentication: checks session (evidence: `apps/web/src/core/routing/hooks/useAppRouter.ts`)
- App routing → Route factory: builds routes (evidence: `apps/web/src/core/routing/hooks/useAppRouter.ts`)
- Route factory → Module routes: creates routes (evidence: `apps/web/src/core/routing/utils/routerFactory.tsx`)
- Route factory → Dashboard: redirects to (evidence: `apps/web/src/core/routing/utils/routerFactory.tsx`)
- Module federation → App routing: provides modules
- Server module loader → Module metadata: gathers metadata (evidence: `apps/api/src/core/functions/modules/loadAndRegisterModuleRoutes.ts`)
- User → Dashboard: manages life (evidence: `README.md`)
- User → Personalization: customizes experience (evidence: `README.md`)
- User → Account settings: manages account
- API application → Core API routes: mounts routes (evidence: `apps/api/src/core/app.ts`)
- Core API routes → Authentication: routes to (evidence: `apps/api/src/core/routes/core.routes.ts`)
- Core API routes → Database services: routes to (evidence: `apps/api/src/core/routes/core.routes.ts`)
- Core API routes → User services: routes to (evidence: `apps/api/src/core/routes/core.routes.ts`)
- Core API routes → API keys: routes to (evidence: `apps/api/src/core/routes/core.routes.ts`)
- Core API routes → Font services: routes to (evidence: `apps/api/src/core/routes/core.routes.ts`)
- Core API routes → AI services: routes to (evidence: `apps/api/src/core/routes/core.routes.ts`)
- Route controller → Request processing: parses payload (evidence: `apps/api/src/core/functions/routes/functions/controllerLogic.ts`)
- Route controller → Response handling: sends response (evidence: `apps/api/src/core/functions/routes/functions/controllerLogic.ts`)
- User → Self-hosted server: controls data (evidence: `README.md`)
- Backups → Self-hosted server: backs up data
- Account settings → Authentication: configures security
