# flomp/wanderer architecture

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

- Interactive diagram: https://gitdiagram.com/flomp/wanderer
- Repository: https://github.com/flomp/wanderer

## Overview

##### Main Components
- Frontend: Located in the “web” directory, this is implemented using Svelte with TypeScript. It handles user interactions by displaying trails, maps, lists, profiles, and settings. This component includes many UI components (buttons, modals, forms, map visualizations) and is responsible for contacting backend APIs.
- Backend / API Server: Found under the “db” directory, this Go-based service includes the main entry point, migrations, integrations (for third-party services like Komoot and Strava), and various utilities. It exposes a RESTful API (organized in routes like /api/v1/...) that serves data to the frontend and handles business logic such as authentication, trail management, and notifications.
- Search Service: The “search” directory hints at a separate container/service (with its own Dockerfile and an entrypoint) that likely assists in indexing and querying trail data. Additionally, MeiliSearch appears referenced in migrations and utility functions under “db/util”, so it is part of the search capability.
- Documentation: The “docs” folder contains an Astro-based site with detailed documentation, guides, and assets (images, videos). While it may not be a runtime component, it supports user/developer onboarding.
- Orchestration / Deployment: The presence of a “docker-compose.yml” file indicates that the various components (frontend, backend, search, and possibly a database or MeiliSearch instance) are containerized and orchestrated together.
- External Integrations: The backend includes directories for integration with third-party APIs such as Komoot and Strava. These integrations are separate sub-components that handle data mapping and synchronization with external systems.

##### Architectural Patterns and Design Principles
- Microservices / Containerization: Each major component is containerized and deployed via Docker Compose. Even if the services share the same repository, think in terms of isolated containers communicating through defined interfaces.
- API-First Communication: The frontend relies on a comprehensive set of API endpoints (organized under /api/v1/...) to interact with the backend, ensuring a loosely coupled architecture.
- Extensibility: The integration directories and modular organization (e.g., separate models, utilities, and stores in the frontend) show that adding new integrations or features is straightforward.

##### Relevant Technologies, Frameworks, and Libraries
- Frontend: Svelte, TypeScript, Vite (as indicated by “vite.config.ts”), Tailwind CSS, and Playwright for testing.
- Backend: Go (with Go modules and migrations), supporting integrations with external services, and built-in utilities for email templates, notifications, and search.
- Search: Likely using MeiliSearch (as inferred from migration file names and utility files).
- Documentation: Astro for the docs site.
- DevOps: Docker Compose and GitHub Actions for CI/CD (as seen in the “.github/workflows” directory).

## Diagram (Mermaid)

```mermaid
flowchart TD
    O("Container Orchestration (Docker Compose)"):::orchestration
    subgraph "Containerized Services"
        FE("Frontend (Svelte, Vite, Tailwind)"):::frontend
        BE("Backend (Go REST API, Komoot/Strava integrations)"):::backend
        SR("Search Service (MeiliSearch)"):::search
    end
    DOC("Documentation (Astro)"):::docs
    KOM("External Integration: Komoot"):::external
    STR("External Integration: Strava"):::external

    O --> FE
    O --> BE
    O --> SR
    FE -->|"HTTP/API"| BE
    BE -->|"SearchQueries"| SR
    BE -.->|"integration"| KOM
    BE -.->|"integration"| STR

    click O "https://github.com/flomp/wanderer/blob/main/docker-compose.yml"
    click FE "https://github.com/flomp/wanderer/tree/main/web"
    click BE "https://github.com/flomp/wanderer/blob/main/db/main.go"
    click SR "https://github.com/flomp/wanderer/tree/main/search/Dockerfile"
    click DOC "https://github.com/flomp/wanderer/tree/main/docs"
    click KOM "https://github.com/flomp/wanderer/tree/main/db/integrations/komoot"
    click STR "https://github.com/flomp/wanderer/tree/main/db/integrations/strava"

    classDef orchestration fill:#D6DBDF,stroke:#566573,stroke-width:2px;
    classDef frontend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef backend fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef search fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef docs fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef external fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
```
