# rotexhawk/daridictionary architecture

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

- Interactive diagram: https://gitdiagram.com/rotexhawk/daridictionary
- Repository: https://github.com/rotexhawk/daridictionary

## Overview

##### Project Type and Purpose
- Dari Dictionary is an open-source project providing an English-to-Dari dictionary. Its goal is to compile comprehensive definitions, including mixtures of Dari and Farsi words, and it benefits from community contributions.
- The project also features automated email functionalities for daily words and welcome messages, indicated by the integration of a subproject called “foundation-emails.”

##### Analyzing the File Structure
- There are clear separations between different aspects of the system:
- The main application under the “src” directory includes several subdirectories such as:
- api: Likely exposing endpoints;
- assets: For static content (JS, Sass, etc.);
- command-bus: Contains scheduled/executable jobs (e.g., generating sitemaps, sending daily words, unblocking visitors);
- config: Contains configuration files (app settings, database details, user agents);
- controllers: Handling business logic for dictionary operations (subscription, confirmation, word definitions);
- models: Representing database or domain objects (DariWord, EnglishWord, etc.);
- middleware: Providing error handling, logging, SEO handling, and other request processing;
- routes: Mapping HTTP endpoints to controllers;
- views: Templates for web pages and emails.
- The “foundation-emails” directory is dedicated to building email templates, containing its own source assets, layouts, pages, and partials.
- There are public directories for static assets, such as CSS, fonts, images, and JavaScript which support the web interface.
- Additional files like webpack.config.js, gulpfile in foundation-emails, package.json files, and test routes indicate building, deployment, and testing pipelines.

a. Main Components:
- Web Frontend:
- Located in “src/web” and “src/views” providing the user interface and templating.
- Public directory holding pre-compiled assets.
- API / Backend:
- “src/api” (and supporting “src/controllers”, “src/models”, “src/routes”, “src/middleware”) forming a RESTful API for dictionary content.
- “src/config” for application and database settings.
- Background / Command Bus:
- “src/command-bus” that schedules or executes tasks such as sending daily words or managing sitemap generation.
- Email Template System:
- “foundation-emails” directory which includes email-specific assets, layouts, pages, and configuration (gulpfile, package).
- Data Layer:
- Database interface is hinted at through “src/db.js” and model definitions in “src/models.”

b. Relationships and Interactions:
- The Frontend interacts with the backend API endpoints defined in “src/api” through routes.
- Controllers manage business logic to fetch and update dictionary data using models, while middleware intercepts requests for logging, error handling, and SEO handling.
- The Command Bus executes background tasks that both interact with the database and trigger email dispatches.
- The Email Template System (foundation-emails) generates content that is integrated with email-based notifications (likely triggered by components in the command bus).
- Configurations from “src/config” feed into multiple modules (controllers, models, middleware) as part of initialization.

c. Architectural Patterns/Design Principles:
- MVC-like separation: Controllers, Models, and Views are clearly separated.
- Modular design: Different responsibilities (API, command bus tasks, email templating) are divided into their respective directories.
- Use of middleware to apply cross-cutting concerns across routes.
- Clear separation between the front-end (user-facing pages) and backend services.
- Utilization of build/configuration tools such as Webpack and Gulp for asset management and templating.

d. Technologies & Frameworks:
- Node.js is the primary environment, as indicated by JavaScript files, package.json, and Node-style modules.
- Frontend styling is managed with Sass (files under “src/assets/sass” and “foundation-emails/src/assets/scss”).
- Template engine (possibly Nunjucks indicated by the ".nunj" file extensions) is used for HTML page construction.
- Additional libraries used in the project for functionalities like email handling, sitemap generation, logging, etc.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Web Frontend
    subgraph "Web Frontend"
        FE1["Index (Client-side Logic)"]:::frontend
        FE2["Views (Templates & Page Layouts)"]:::frontend
        FE3["Static Assets"]:::frontend
    end

    %% API Backend
    subgraph "API Backend"
        API["API Endpoints"]:::backend
        CTRL["Controllers"]:::backend
        MODEL["Models"]:::backend
        ROUTE["Routes"]:::backend
        MW["Middleware"]:::backend
        CONF["Configuration"]:::backend
    end

    %% Background Tasks (Command Bus)
    subgraph "Background Tasks"
        BUS["Background Tasks (Command Bus)"]:::command
    end

    %% Email Template System
    subgraph "Email Template System"
        EMAIL["Email Assets & Layouts"]:::email
    end

    %% Data Layer
    subgraph "Data Layer"
        DB[(Database Connection)]:::database
    end

    %% Relationships between components
    FE1 -->|"calls"| API
    API -->|"uses"| MW
    API -->|"routes"| ROUTE
    ROUTE -->|"invokes"| CTRL
    CTRL -->|"accesses"| MODEL
    API -->|"fetches data"| DB
    CONF -->|"configures"| API
    BUS -->|"triggers"| EMAIL
    BUS -->|"updates"| DB
    FE2 -.->|"renders output"| FE1

    %% Class definitions for colors
    classDef frontend fill:#a1cfff,stroke:#000,stroke-width:2px;
    classDef backend fill:#a1f7a1,stroke:#000,stroke-width:2px;
    classDef command fill:#ffdf80,stroke:#000,stroke-width:2px;
    classDef email fill:#d1a3ff,stroke:#000,stroke-width:2px;
    classDef database fill:#fdd,stroke:#000,stroke-width:2px;

    %% Click Events for Web Frontend
    click FE1 "https://github.com/rotexhawk/daridictionary/blob/master/src/web/index.js"
    click FE2 "https://github.com/rotexhawk/daridictionary/tree/master/src/views"
    click FE3 "https://github.com/rotexhawk/daridictionary/tree/master/public"

    %% Click Events for API / Backend
    click API "https://github.com/rotexhawk/daridictionary/tree/master/src/api"
    click CTRL "https://github.com/rotexhawk/daridictionary/tree/master/src/controllers"
    click MODEL "https://github.com/rotexhawk/daridictionary/tree/master/src/models"
    click ROUTE "https://github.com/rotexhawk/daridictionary/tree/master/src/routes"
    click MW "https://github.com/rotexhawk/daridictionary/tree/master/src/middleware"
    click CONF "https://github.com/rotexhawk/daridictionary/tree/master/src/config"

    %% Click Event for Background / Command Bus
    click BUS "https://github.com/rotexhawk/daridictionary/tree/master/src/command-bus"

    %% Click Event for Email Template System
    click EMAIL "https://github.com/rotexhawk/daridictionary/tree/master/foundation-emails"

    %% Click Event for Data Layer
    click DB "https://github.com/rotexhawk/daridictionary/blob/master/src/db.js"
```
