# anxiko/needlist architecture

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

- Interactive diagram: https://gitdiagram.com/anxiko/needlist
- Repository: https://github.com/anxiko/needlist

## Overview

##### Main layers and components
- Web Frontend: This is defined primarily by the files in the “assets” directory (CSS, JavaScript, Tailwind config, vendor files). These assets support client-side functionalities (like dark mode and initial setup) and are served through Phoenix’s rendering layer.
- Phoenix Web Server: Located in “lib/needlist_web”, this layer includes controllers, templates (HEEx files), live views, components, and the router. It is the entry point for HTTP requests (as indicated by mix commands for starting the Phoenix server).
- Business/Domain Logic: The “lib/needlist” directory houses the core application logic, such as account management, Discogs API integrations, listing/scraping logic, OAuth, and other business rules. Notice also the custom modules like “atom_enum”, “ecto_extra”, and “needlist” which encapsulate domain-specific operations.
- Persistence/Database Layer: Managed by Ecto (the “lib/needlist/repo” modules and “priv/repo” migrations). This layer handles interactions with the SQL database (with migrations, seeds, fixtures) to store data related to users, listings, wantlists, etc.
- External Integrations: The project integrates with Discogs (as seen in directories like “lib/needlist/discogs” and Python scripts in “priv/python/”) to handle scraping and API interactions. OAuth integration for users may also be part of this external communication layer.
- Background & Mix Tasks: The “lib/mix/tasks/scrape” directory suggests background tasks or CLI scripts for scraping or data processing, emphasizing the importance of periodic or ad-hoc job execution.

##### Component Interactions
- Clients (web browsers) communicate with the Phoenix web server via HTTP(S).
- The Phoenix controllers and live views route requests to the corresponding business logic in “needlist” modules.
- These business logic components interact with the database through the Ecto repository.
- For integration with external services (like Discogs), specialized modules and even Python scripts are used to scrape or retrieve data which is then absorbed into the business layer.
- Mix tasks may be invoked for data processing or routine scraping, interacting either directly with the Ecto repo or the external API components.

##### Architectural Patterns and Design Principles
- MVC (Model-View-Controller) Pattern: Explicitly seen in the separation of “controllers” (handling HTTP requests), “views” (rendering HTML with HEEx templates), and “models” (business logic, Ecto schemas, and repo).
- Separation of Concerns: The project clearly divides assets, configuration, application logic, and web interface layers.
- Modular Design: The “lib/needlist” directory is further broken down (accounts, discogs, repo, types) to isolate functionalities.
- External Integration Abstraction: Dedicated directories for handling Discogs API, OAuth, and scraping indicate a clean separation between local business logic and third-party interactions.

##### Key Technologies & Frameworks
- Phoenix Framework (for building the web interface and HTTP API endpoints).
- Elixir and the underlying BEAM runtime.
- Ecto (for database interactions, migrations, and repository pattern).
- Tailwind CSS (configured in the assets for styling).
- Additional modules and tasks (like custom mix tasks, Python scripts for scraping, etc.) that support auxiliary functions.

##### Elements
- Optional: Highlight mix tasks as auxiliary components that trigger scraping or background jobs.

##### Putting It All Together
- Server to the “Business Logic” layer – a cluster containing modules for different domains (accounts, discogs operations, listings, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    A["Web Browser"]:::client

    %% Web Frontend Layer
    subgraph "Web Frontend"
        FE["Assets"]:::frontend
    end

    %% Phoenix Web Server Layer
    subgraph "Phoenix Web Server"
        WS["Controllers, Views, Live Views, Router"]:::server
    end

    %% Business/Domain Logic Layer
    subgraph "Business/Domain Logic"
        BL["Core Business Logic"]:::business
    end

    %% Persistence/Database Layer
    subgraph "Persistence/Database Layer"
        R["Ecto Repository"]:::db
        M["Migrations & Seeds"]:::db
        DB["SQL Database"]:::db
    end

    %% External Integrations Layer
    subgraph "External Integrations"
        DI["Discogs & OAuth"]:::external
        PS["Python Scraper"]:::external
    end

    %% Background & Mix Tasks Layer
    subgraph "Background & Mix Tasks"
        MT["Mix Tasks (Scrape)"]:::tasks
    end

    %% Connections
    A -->|"HTTP_Request"| FE
    FE -->|"Asset_Delivery"| WS
    WS -->|"Invokes"| BL
    BL -->|"Uses"| R
    R -->|"Performs_DB_Operations"| DB
    BL -->|"Triggers"| M
    BL -->|"Calls"| DI
    BL -->|"Invokes"| PS
    MT -->|"Executes"| BL
    MT -->|"Updates"| R

    %% Click Events
    click FE "https://github.com/anxiko/needlist/tree/master/assets/"
    click WS "https://github.com/anxiko/needlist/tree/master/lib/needlist_web/"
    click BL "https://github.com/anxiko/needlist/tree/master/lib/needlist/"
    click R "https://github.com/anxiko/needlist/tree/master/lib/needlist/repo/"
    click M "https://github.com/anxiko/needlist/tree/master/priv/repo/"
    click DI "https://github.com/anxiko/needlist/tree/master/lib/needlist/discogs/"
    click PS "https://github.com/anxiko/needlist/tree/master/priv/python/"
    click MT "https://github.com/anxiko/needlist/tree/master/lib/mix/tasks/scrape/"

    %% Styles
    classDef client fill:#ffecb3,stroke:#f57c00,stroke-width:2px;
    classDef frontend fill:#aed581,stroke:#33691e,stroke-width:2px;
    classDef server fill:#64b5f6,stroke:#0d47a1,stroke-width:2px;
    classDef business fill:#ffb74d,stroke:#ef6c00,stroke-width:2px;
    classDef db fill:#81c784,stroke:#2e7d32,stroke-width:2px;
    classDef external fill:#ba68c8,stroke:#6a1b9a,stroke-width:2px;
    classDef tasks fill:#e57373,stroke:#d32f2f,stroke-width:2px;
```
