# raoul2000/fs-explorer architecture

> Architecture diagram of the GitHub repository raoul2000/fs-explorer, 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/raoul2000/fs-explorer
- Repository: https://github.com/raoul2000/fs-explorer

## Overview

##### Main Components
- Backend: Represented by "src/back". This side is organized into:
– Configuration (e.g., "src/back/config.clj")
– Domain logic ("src/back/domain") where you have modules like action, explorer (with its core, metadata, type modules), open_file, process, and say_hello.
– Server layer ("src/back/server") which contains handlers for various endpoints (e.g., home, info, greet, explorer, etc.), routes definitions, and a response abstraction.
– The system initialization/configuration inside "src/back/system.clj".
- Shared Modules: Located in "src/shared", these modules provide cross-cutting definitions or models (such as "model.cljc") that can be used by both the frontend and backend.
- Development & Testing Tools: Notice directories like "src/dev", various configuration files (deps.edn, build.clj, shadow-cljs.edn), and test directories ("test/back" and "test/front") that manage automated tests and provide fixtures for local development.
- Resources & Static Assets: The "resources/public" directory contains static files (CSS, fonts, images, and index.html) that support the UI.

##### Out the Relationships & Data Flow
- API Layer: Clearly denote that the REST endpoints (handlers inside "src/back/server/handler") cater to different functionalities like file exploration, configuration access, greeting, and file downloads.
- Domain-Driven Design: Within the backend, show how the different domain modules (e.g., explorer, actions, file operations) are orchestrated by the server endpoints.
- Development/Build Process Integration: Highlight the role of build tools (shadow-cljs for frontend and build scripts in "tools") and how they tie the two halves of the stack together. These pieces are essential when creating production builds.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Clearly separate the frontend from the backend. Indicate that the frontend handles the UI and client-side logic while the backend gives a robust REST API to interact with the file system logic.
- Modularity: The clear division of the backend into domain logic, configuration, and server-related modules.
- Full-Stack Integration: Emphasize how both ends are integrated through clearly defined API boundaries.
- Testing and DevOps: Include separate nodes for testing (integration and unit tests) and build scripts that aid the continuous integration build process.

##### Technologies, Frameworks, and Tools
- Clojure & ClojureScript as main languages.
- Pedestal as the backend web server framework.
- Shadow-cljs for managing the frontend (and handling the live reload/build process).
- Node (along with npm scripts and package.json) for managing frontend dependencies.
- Build and dependency management via deps.edn and build.clj.
- VSCode (with Calva and REST Client extensions) for development and API testing.

##### Essential Elements
- Clear Labels: Name each component (e.g., "Frontend UI", "API Gateway", "File Explorer Domain", "Pedestal Server", "Shared Models").
- Integration Points: Highlight where external services (like the shadow-cljs server and Node package management) interact with the project.
- Annotations: Optionally include notes such as “Compiled by shadow-cljs”, “Handles HTTP requests”, “Manages file system operations”, and “Shared models between front and back”.

##### Final Recommendations
- Be as detailed as possible. Include each main directory as a separate component if it contributes to the project’s functionality.
- Avoid over-complicating; the idea is to clearly map out the key areas, their responsibilities, and their interactions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend"
        FE_UI["Frontend UI (src/front)"]:::frontend
        FE_Components["Components (src/front/components)"]:::frontend
        FE_Pages["Pages (src/front/page)"]:::frontend
        FE_Routing["Routing (src/front/route)"]:::frontend
        FE_DB["State Management (src/front/db.cljs)"]:::frontend
        FE_UI --> FE_Components
        FE_UI --> FE_Pages
        FE_UI --> FE_Routing
        FE_UI --> FE_DB
    end

    subgraph "Backend"
        BE_HTTP["HTTP Routing & REST Endpoints (src/back/server)"]:::backend
        BE_API["API Handlers (src/back/server/handler)"]:::backend
        BE_Response["Response Abstraction (src/back/server/response.clj)"]:::backend
        BE_Domain["Domain Logic (src/back/domain)"]:::backend
        BE_System["System Initialization (src/back/system.clj)"]:::backend
        BE_Config["Configuration (src/back/config.clj)"]:::backend
        BE_HTTP -->|"routes"| BE_API
        BE_API -->|"orchestrates"| BE_Domain
        BE_API -->|"formats"| BE_Response
    end

    subgraph "Shared Modules"
        Shared["Shared Models (src/shared)"]:::shared
    end

    subgraph "Dev & Testing"
        Dev["Development Tools (src/dev)"]:::dev
        Test_Back["Backend Tests (test/back)"]:::dev
        Test_Front["Frontend Tests (test/front)"]:::dev
    end

    subgraph "Build & Assets"
        Build["Build Tools & Dependency Management (tools, deps.edn, build.clj, shadow-cljs.edn)"]:::build
        Assets["Static Assets (resources/public)"]:::assets
    end

    FE_UI -->|"API_Call"| BE_HTTP
    BE_Domain -->|"uses"| Shared
    FE_UI -->|"utilizes"| Shared
    Build -->|"compiles"| FE_UI
    Build -->|"builds"| BE_System
    FE_UI -->|"loads"| Assets
    Dev -->|"supports"| FE_UI
    Dev -->|"supports"| BE_System

    %% Click Events
    click FE_UI "https://github.com/raoul2000/fs-explorer/tree/main/src/front"
    click FE_Components "https://github.com/raoul2000/fs-explorer/tree/main/src/front/components"
    click FE_Pages "https://github.com/raoul2000/fs-explorer/tree/main/src/front/page"
    click FE_Routing "https://github.com/raoul2000/fs-explorer/tree/main/src/front/route"
    click FE_DB "https://github.com/raoul2000/fs-explorer/blob/main/src/front/db.cljs"
    click BE_HTTP "https://github.com/raoul2000/fs-explorer/tree/main/src/back/server"
    click BE_API "https://github.com/raoul2000/fs-explorer/tree/main/src/back/server/handler"
    click BE_Response "https://github.com/raoul2000/fs-explorer/blob/main/src/back/server/response.clj"
    click BE_System "https://github.com/raoul2000/fs-explorer/blob/main/src/back/system.clj"
    click BE_Config "https://github.com/raoul2000/fs-explorer/blob/main/src/back/config.clj"
    click BE_Domain "https://github.com/raoul2000/fs-explorer/tree/main/src/back/domain"
    click Shared "https://github.com/raoul2000/fs-explorer/tree/main/src/shared"
    click Dev "https://github.com/raoul2000/fs-explorer/tree/main/src/dev"
    click Test_Back "https://github.com/raoul2000/fs-explorer/tree/main/test/back"
    click Test_Front "https://github.com/raoul2000/fs-explorer/tree/main/test/front"
    click Build "https://github.com/raoul2000/fs-explorer/tree/main/tools"
    click Assets "https://github.com/raoul2000/fs-explorer/tree/main/resources/public"

    %% Styles
    classDef frontend fill:#A2D5F2,stroke:#333,stroke-width:2px;
    classDef backend fill:#FFB3BA,stroke:#333,stroke-width:2px;
    classDef shared fill:#C3FDB8,stroke:#333,stroke-width:2px;
    classDef dev fill:#FDFD96,stroke:#333,stroke-width:2px;
    classDef build fill:#D3BCE3,stroke:#333,stroke-width:2px;
    classDef assets fill:#F5B7B1,stroke:#333,stroke-width:2px;
```
