# scpwiki/wikijump architecture

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

- Interactive diagram: https://gitdiagram.com/scpwiki/wikijump
- Repository: https://github.com/scpwiki/wikijump

## Overview

##### Project Type and Purpose
- Wikijump is a full‑stack wiki/collaboration platform developed as an evolution of the legacy Wikidot system.
- It features a modern Rust‑based backend (in the “deepwell” directory) handling business logic, data models, endpoints, and services; a modern Svelte/TypeScript frontend (in “framerail”); and support for legacy PHP modules (in “legacy”) that may still be referenced or maintained.
- The project also includes extensive deployment scripts (Docker, AWS/Terraform configurations in “install”), localization resources, and additional “web” modules for extra front‑end assets or API definitions.

##### Analyzing the File Structure
- Look for clearly separated high‑level components:
- “deepwell”: This folder holds the Rust backend code. Inside it are subdirectories for configuration, endpoints, models, database access, various business logic “services” (e.g., authentication, paging, rendering, etc.) and integration with external systems (Redis, file revisions, caching).
- “framerail”: Contains the modern frontend components built using Svelte, TypeScript, and associated libraries that interface with the backend API.
- “legacy”: Contains legacy PHP code – this is a separate subsystem that might interact with or be superseded by the deepwell services.
- “install”: Contains environment-specific configurations and deployment scripts (for local, dev, and prod) using Docker, AWS, Terraform, etc.
- “locales”: Contains translation files and localization configurations (using Fluent, cmftml, and typed variants).
- “web”: Contains additional web assets, API documentation (OpenAPI definitions in “web/modules/api”), helper scripts, and resource views.

##### Key Components
a. Backend (Deepwell):
– Subdivide into key modules such as:
- API/Endpoints (each file in deepwell/src/endpoints)
- Business Services (e.g., authentication, file, message, user, page, etc.)
- Data Models and Database Access (deepwell/src/models and deepwell/src/database)
- Auxiliary Services like caching (Redis integration), job workers, and special pages.
– Illustrate how these layers interact with external systems:
- Database (PostgreSQL, as suggested by “postgres” in the install folders)
- Caching system (Redis)
- File storage (MinIO configuration present in install/local/minio)
b. Frontend (Framerail):
– Represent the modern Svelte components and routes that render the wiki content and manage client‐side interactions.
– Note its communication channel with the deepwell backend via APIs.
c. Legacy System:
– Represent the legacy PHP codebase as a separate legacy subsystem that might either run side‑by‑side or serve as a “migration reference” for new deepwell services.
d. Deployment and Infrastructure:
– Include separate nodes for deployment configurations (Docker, AWS/Terraform setups), referencing the “install” directories and GitHub Actions workflows.
– Indicate different environments (dev, local, prod) with deployment pipelines.
e. Localization:
– Represent localization modules using the “locales” directories (Fluent, cmftml, typed, and validator) which integrate with both the frontend and backend to provide multilingual support.

##### Relationships and Interactions
- User browsers interact with the Framerail frontend.
- Framerail makes API calls to the Deepwell backend.
- Deepwell accesses and updates the Database, caches with Redis, and integrates with external services (email, file storage, etc.).
- Deployment tools (Docker, Terraform) orchestrate containerized services in the production environment.
- Localization services feed translation data into both frontend and backend components.

##### Architectural Patterns/Design Principles
- Layered/MVC-like separation: Separate presentation (Framerail), business logic (Deepwell services and endpoints), and data persistence (database access).
- Separation of concerns: Different modules for authentication, file management, rendering, and so on.
- Environment-driven deployments: Highlight the use of Docker containers, AWS/Terraform scripts for production, and local development support.
- Clear API boundaries: Emphasize that the modern frontend interacts with the backend through RESTful APIs or possibly GraphQL endpoints.

- “Database” (PostgreSQL)
- “Cache” (Redis)
- “File Storage” (MinIO)
- “External Services” (email, etc.)
- A layer for “Deployment Infrastructure” showing Docker, AWS/Terraform CI/CD pipelines (installation scripts and GitHub Actions workflows).
- A “Localization” component and indicate that it feeds data to both Frontend and Backend.
- Use labels like “Deepwell (Rust)” and “Framerail (Svelte/TS)” so viewers immediately grasp the tech stacks.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Nodes
    User["User (Browser)"]:::external

    %% Frontend Layer
    subgraph "Frontend (Framerail - Svelte/TS)"
        FR["Framerail (Svelte/TS)"]:::frontend
        FR_src["Source (framerail/src)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Deepwell - Rust)"
        DW["Deepwell (Rust)"]:::backend
        DW_src["Source (deepwell/src/)"]:::backend
        DW_config["Config (deepwell/config.example.toml)"]:::backend
        DW_mig["Migrations (deepwell/migrations)"]:::backend
        DW_serv["Services (deepwell/services)"]:::backend
        DW_models["Models & DB Access (deepwell/src/models & deepwell/src/database)"]:::backend
    end

    %% Legacy System
    subgraph "Legacy System (PHP)"
        LEG["Legacy System (PHP)"]:::legacy
        LEG_readme["README (legacy/README.md)"]:::legacy
        LEG_app["Application (legacy/app/)"]:::legacy
        LEG_php["PHP Code (legacy/php/)"]:::legacy
        LEG_web["Web Assets (legacy/web/)"]:::legacy
    end

    %% Deployment and Infrastructure
    subgraph "Deployment & Infrastructure"
        DEP["Deployment (Docker/AWS/Terraform)"]:::deployment
        DEP_aws["AWS Configs (install/aws)"]:::deployment
        DEP_dev["Dev Environment (install/dev)"]:::deployment
        DEP_local["Local Setup (install/local)"]:::deployment
        DEP_prod["Prod Environment (install/prod)"]:::deployment
    end

    %% Localization Services
    subgraph "Localization"
        LOC["Localization Service"]:::localization
        LOC_fluent["Fluent (locales/fluent)"]:::localization
        LOC_typed["Typed (locales/typed)"]:::localization
        LOC_validator["Validator (locales/validator)"]:::localization
    end

    %% Additional Web Assets / API Definitions
    subgraph "Additional Web Assets / API Definitions"
        WEB["Web Assets & API Docs"]:::external
        WEB_api["API Modules (web/modules/api)"]:::external
        WEB_res["Resource Views (web/resources)"]:::external
    end

    %% External Dependencies for Backend
    DB["Database (PostgreSQL)"]:::external
    Cache["Cache (Redis)"]:::external
    FS["File Storage (MinIO)"]:::external

    %% Relationships and Interactions
    User -->|"interacts"| FR
    FR -->|"calls_API"| DW
    DW -->|"manages"| DW_models
    DW -->|"configured_by"| DW_config
    DW -->|"migrates_with"| DW_mig
    DW -->|"executes"| DW_serv
    DW -->|"integrates"| DW_src

    %% Backend External Dependencies
    DW -->|"queries"| DB
    DW -->|"caches_with"| Cache
    DW -->|"stores_files_in"| FS

    %% Legacy System Connection
    User -.->|"historic_routes"| LEG

    %% Deployment Relationships
    DEP -->|"deploys"| FR
    DEP -->|"deploys"| DW
    DEP -->|"deploys"| LEG
    DEP_aws --> DEP
    DEP_dev --> DEP
    DEP_local --> DEP
    DEP_prod --> DEP

    %% Localization Feeds
    LOC -->|"feeds_FR"| FR
    LOC -->|"feeds_DW"| DW

    %% Web Assets Integration
    FR -->|"loads_assets_from"| WEB
    WEB -->|"defines_API_for"| DW

    %% Click Events
    click DW "https://github.com/scpwiki/wikijump/tree/develop/deepwell"
    click DW_src "https://github.com/scpwiki/wikijump/tree/develop/deepwell/src/"
    click DW_config "https://github.com/scpwiki/wikijump/blob/develop/deepwell/config.example.toml"
    click DW_mig "https://github.com/scpwiki/wikijump/tree/develop/deepwell/migrations"
    click DW_serv "https://github.com/scpwiki/wikijump/tree/develop/deepwell/services"
    
    click FR "https://github.com/scpwiki/wikijump/tree/develop/framerail"
    click FR_src "https://github.com/scpwiki/wikijump/tree/develop/framerail/src/"

    click LEG "https://github.com/scpwiki/wikijump/tree/develop/legacy"
    click LEG_readme "https://github.com/scpwiki/wikijump/blob/develop/legacy/README.md"
    click LEG_app "https://github.com/scpwiki/wikijump/tree/develop/legacy/app/"
    click LEG_php "https://github.com/scpwiki/wikijump/tree/develop/legacy/php/"
    click LEG_web "https://github.com/scpwiki/wikijump/tree/develop/legacy/web/"

    click DEP "https://github.com/scpwiki/wikijump/tree/develop/install"
    click DEP_aws "https://github.com/scpwiki/wikijump/tree/develop/install/aws"
    click DEP_dev "https://github.com/scpwiki/wikijump/tree/develop/install/dev"
    click DEP_local "https://github.com/scpwiki/wikijump/tree/develop/install/local"
    click DEP_prod "https://github.com/scpwiki/wikijump/tree/develop/install/prod"

    click LOC "https://github.com/scpwiki/wikijump/tree/develop/locales"
    click LOC_fluent "https://github.com/scpwiki/wikijump/tree/develop/locales/fluent"
    click LOC_typed "https://github.com/scpwiki/wikijump/tree/develop/locales/typed"
    click LOC_validator "https://github.com/scpwiki/wikijump/tree/develop/locales/validator"

    click WEB "https://github.com/scpwiki/wikijump/tree/develop/web"
    click WEB_api "https://github.com/scpwiki/wikijump/tree/develop/web/modules/api"
    click WEB_res "https://github.com/scpwiki/wikijump/tree/develop/web/resources"

    %% Styles
    classDef backend fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef frontend fill:#BBDEFB,stroke:#1565C0,stroke-width:2px;
    classDef legacy fill:#E0E0E0,stroke:#424242,stroke-dasharray: 5 5,stroke-width:2px;
    classDef deployment fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef localization fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
    classDef external fill:#D1C4E9,stroke:#4527A0,stroke-width:2px;
```
