# foambubble/foam architecture

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

## Overview

##### Main Components
- VS Code Extension Layer: The core of Foam lies in the extension (packages/foam-vscode). Break this down further into:
– Core Modules and Utilities: Look in the src/core folder (with subcomponents for common functionality, models, services, utilities, and janitor routines). These components handle markdown parsing, link management, file navigation, autocompletion, and data-store interactions.
– Feature Modules: In the src/features folder, you see components implementing commands (create note, open daily note, convert links), panels (graph visualization, backlinks, tags explorer), preview functionalities, link diagnostics, embedding and more.
– Services: Under src/services, components for configuration, templates, variable resolution, logging, and file watchers exist to provide background operations.
– Test and Type Definitions: The presence of tests in src/test and TypeScript definitions ensures that each module is well-specified.

- Workspace/Documentation: The docs/ folder includes guidelines, use case recipes, tutorials, and configuration for static sites. This documentation supports both users and developers in understanding project functionality.

- Static Assets: The assets/ and packages/foam-vscode/static directories provide images, CSS, JavaScript, and HTML for features like graph visualizations and the preview mode.

- External Dependencies & Integration Points:
– VS Code APIs: Interaction with the VS Code command palette, editors, and UI panels.
– Git and Markdown: Foam is built for integration with Git (via GitHub and local repos) and uses markdown as its fundamental storage format.
– Optional Publishing / Webview: Some features (like the graph visualization) may use embedded web views or static assets deployed in user workspaces.

##### Relationships and Interactions
- The user operates from within VS Code. The extension intercepts commands, listens for file changes (using file watchers) and integrates with the command palette.
- The Core Services process markdown notes (stored as flat files in the user’s workspace) and maintain an internal model of “notes,” links, graph nodes, and so on.
- Feature modules (e.g., backlink and tag panels) query the underlying model and update views in response to changes.
- Utility and helper modules offer shared functionality such as error handling, logging, and caching.
- Static assets support visualization (graph view, preview panels) by sending data from VS Code’s extension back-end to a web view or browser-like component.

##### Architectural Patterns and Design Principles
- Modular design: The project is decomposed into clearly separated modules (core, features, services, utilities) which is evident from the folder hierarchy.
- Event-driven and reactive updates: Source files (with event.ts, lifecycle.ts, and watchers) indicate an architecture that reacts to user commands and file changes.
- Test-driven development: The inclusion of tests alongside file-specific logic (e.g., *.test.ts files) indicates a commitment to unit testing.
- Extensibility and configuration management: The rich set of configuration files and documentation points toward a design that is easily extended by users and contributors.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User("User"):::external
    Workspace("Local Markdown Workspace"):::external
    VSCodeAPIs("VS Code APIs"):::external

    ext("VS Code Extension (Foam)"):::core
    click ext "https://github.com/foambubble/foam/tree/main/packages/foam-vscode"

    subgraph "Extension Components"
        subgraph "Core Modules & Utilities"
            coreFunc("Core Functionality"):::core
            click coreFunc "https://github.com/foambubble/foam/tree/main/packages/foam-vscode/src/core"
            coreCommon("Common Utilities"):::core
            click coreCommon "https://github.com/foambubble/foam/tree/main/packages/foam-vscode/src/core/common"
            coreUtils("Additional Utilities"):::core
            click coreUtils "https://github.com/foambubble/foam/tree/main/packages/foam-vscode/src/core/utils"
            janitor("Janitor Routines"):::core
            click janitor "https://github.com/foambubble/foam/tree/main/packages/foam-vscode/src/core/janitor"
            dataModel("Data Models"):::core
            click dataModel "https://github.com/foambubble/foam/tree/main/packages/foam-vscode/src/core/model"
        end

        subgraph "Feature Implementations"
            commands("Commands"):::feature
            click commands "https://github.com/foambubble/foam/tree/main/packages/foam-vscode/src/features/commands"
            panels("Panels (Graph,Backlinks,Tags)"):::feature
            click panels "https://github.com/foambubble/foam/tree/main/packages/foam-vscode/src/features/panels"
            preview("Preview Functionalities"):::feature
            click preview "https://github.com/foambubble/foam/tree/main/packages/foam-vscode/src/features/preview"
        end

        services("Background Services"):::service
        click services "https://github.com/foambubble/foam/tree/main/packages/foam-vscode/src/services"

        testing("Testing & Type Definitions"):::test
        click testing "https://github.com/foambubble/foam/tree/main/packages/foam-vscode/src/test"
    end

    subgraph "Supporting Components"
        docs("Documentation & Developer Resources"):::doc
        click docs "https://github.com/foambubble/foam/tree/main/docs"
        static("Static Assets & Webviews"):::asset
        click static "https://github.com/foambubble/foam/tree/main/assets"
        static2("Static Assets (Extension)"):::asset
        click static2 "https://github.com/foambubble/foam/tree/main/packages/foam-vscode/static"
    end

    %% Connections
    User -->|"triggers"| ext
    Workspace -->|"FileUpdates"| coreFunc
    ext -->|"invokes"| VSCodeAPIs
    coreFunc -->|"updates"| dataModel
    dataModel -->|"feeds"| commands
    commands -->|"refreshes"| panels
    commands -->|"triggers"| preview
    commands -->|"calls"| VSCodeAPIs
    services -->|"supports"| coreFunc
    services -->|"watches"| commands
    testing -->|"validates"| coreFunc
    testing -->|"ensures"| services
    panels --> static
    preview --> static2
    docs -->|"guides"| ext
    VSCodeAPIs -->|"providesAPIs"| commands

    %% Styles
    classDef core fill:#AED6F1,stroke:#1A5276,stroke-width:2px;
    classDef feature fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
    classDef service fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef test fill:#D7BDE2,stroke:#7D3C98,stroke-width:2px;
    classDef doc fill:#F5CBA7,stroke:#CA6F1E,stroke-width:2px;
    classDef asset fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef external fill:#D5DBDB,stroke:#566573,stroke-width:2px;
```
