# habitrpg/habitica architecture

> Architecture diagram of the GitHub repository habitrpg/habitica, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/habitrpg/habitica
- Repository: https://github.com/habitrpg/habitica

## Overview

##### And Isolate the Main Components

- Frontend Client:
- Look at the “website/client” directory which contains the Vue.js application (notice the “src”, “components”, “router”, and “store” subdirectories).
- This frontend handles user interfaces, routing, state management, and interacts with backend APIs.

- Backend Server:
- It provides RESTful APIs, authentication, business logic, integration with payment providers (Stripe, PayPal, Amazon, Apple, Google), notifications, and more.

- Database Layer:
- Although a specific “database” directory isn’t obvious, the presence of migration scripts in “migrations” and the use of libraries like “mongodb.js” within the server indicate a NoSQL database (MongoDB is commonly used in Habitica).
- This as a central data store that the backend interacts with.

- External or Third-Party Services:
- Payment processing plugins (e.g., Stripe, PayPal, Amazon, Apple, and Google) are used, as seen in the “server/libs/payments” subdirectories.
- Other integrations include email handling, push notifications (“pushNotifications.js”), and social authentication.
- Services as external integrations that the backend accesses via API calls.

- Infrastructure & Deployment:
- The repository contains Docker files (“Dockerfile-Dev”), docker-compose configurations, Kubernetes YAML files, and build scripts (gulp files, npm configuration).
- These are used for containerizing, orchestrating, testing, and deploying the application.

##### Out the Relationships and Interactions

- User Interaction Flow:
- Users (or players) interact with the Habitica web client, which is built using Vue.js.
- The client makes RESTful (or possibly real-time via websockets) API calls to the backend server.

- Backend Business Logic:
- The server receives client requests through its controllers. The controllers process requests, call various services (for authentication, payments, etc.), and interact with the database via model classes.
- Middleware (e.g., auth, rate limiting, error handling) is applied to these flows to filter, validate, or enrich the data.

- Data Persistence:
- Backend services invoke operations on the database. Migrations in the “migrations” directory show that database state management is explicitly handled.
- Render this as a separate “Database (MongoDB)” component connected directly to the backend.

- Integration with External Services:
- Payment and other external integrations are modules that the backend communicates with for services like processing transactions, sending emails, and notifications.

- DevOps & CI/CD:
- Build pipelines (via gulp, npm scripts, docker-compose, and Kubernetes configurations) ensure automated testing, deployment, and scaling of the application. Show these as supporting components connecting to both the frontend and backend.

##### Architectural Patterns and Design Principles

- Modular and Separation of Concerns:
- The project separates frontend and backend logic, API layers, middleware, and service layers (such as libraries and ops).
- The server controllers follow an MVC-like pattern where the controllers coordinate between models and services.

- Scalability and Microservice-like Integration:
- The use of Docker, Kubernetes, and extensive test suites supports a scalable, production-grade deployment.
- The codebase appears to support versioned APIs (api-v3 and api-v4), indicating incremental and backward-compatible evolution of the architecture.

- Extensibility:
- The presence of plugins (such as payment modules) and a rich set of configuration files (like config.json.example) shows that the system is built to be extended as new features are developed.

##### Final Assembly

▪ API Controllers (v3, v4)
▪ Middleware (auth, error handling, rate limiting)
▪ Business Logic/Services (Payment Processing, Notifications, Chat, etc.)
▪ Data Models & Database Interactions
- “Backend Server” to a “Database (MongoDB)” component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    U["User/Player"]:::user

    %% Frontend Layer
    F["Frontend Client (Vue.js App)"]:::frontend
    U -->|"interacts"| F

    %% Backend Layer
    B["Backend Server\n(API Controllers, Middleware, Services & Models)"]:::backend
    F -->|"Request/Response"| B

    %% Database & Data Persistence
    subgraph "Database & Data Persistence"
        DB["Database (MongoDB)"]:::database
        MIG["Migrations"]:::database
        DR["Database Reports"]:::database
        DB -->|"migration"| MIG
        DB -->|"reports"| DR
    end
    B -->|"DataOperations"| DB

    %% External Services
    subgraph "External Services"
        P1["Payments Lib"]:::external
        P2["Payments Controller"]:::external
        PN["Push Notifications"]:::external
    end
    B -->|"ExternalAPI"| P1
    B -->|"ExternalAPI"| P2
    B -->|"Notify"| PN

    %% Infrastructure & Deployment
    subgraph "Infrastructure & Deployment"
        D1["Dockerfile-Dev"]:::infrastructure
        D2["docker-compose.yml"]:::infrastructure
        D3["docker-compose.dev.yml"]:::infrastructure
        D4["Kubernetes Configurations"]:::infrastructure
    end
    D1 -.->|"Deployment"| F
    D2 -.->|"Deployment"| F
    D3 -.->|"Deployment"| B
    D4 -.->|"Deployment"| B

    %% Click Events
    click F "https://github.com/habitrpg/habitica/tree/develop/website/client/"
    click B "https://github.com/habitrpg/habitica/tree/develop/website/server/"
    click MIG "https://github.com/habitrpg/habitica/tree/develop/migrations/"
    click DR "https://github.com/habitrpg/habitica/tree/develop/database_reports/"
    click P1 "https://github.com/habitrpg/habitica/tree/develop/website/server/libs/payments/"
    click P2 "https://github.com/habitrpg/habitica/tree/develop/website/server/controllers/top-level/payments/"
    click D1 "https://github.com/habitrpg/habitica/tree/develop/Dockerfile-Dev"
    click D2 "https://github.com/habitrpg/habitica/blob/develop/docker-compose.yml"
    click D3 "https://github.com/habitrpg/habitica/blob/develop/docker-compose.dev.yml"
    click D4 "https://github.com/habitrpg/habitica/tree/develop/kubernetes/"

    %% Styles
    classDef user fill:#FFC107,stroke:#000,stroke-width:2px;
    classDef frontend fill:#ACE7FF,stroke:#000,stroke-width:2px;
    classDef backend fill:#B6E1AD,stroke:#000,stroke-width:2px;
    classDef database fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef external fill:#FFD699,stroke:#000,stroke-width:2px;
    classDef infrastructure fill:#E2BBE3,stroke:#000,stroke-width:2px;
```
