# abdelaziz18003/mostalah architecture

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

- Interactive diagram: https://gitdiagram.com/abdelaziz18003/mostalah
- Repository: https://github.com/abdelaziz18003/mostalah

## Overview

##### Project type and purpose
- This is a Node.js–based full-stack web application (server-rendered) whose purpose is to provide an English↔Arabic technical-terms dictionary.
- It includes both a web-UI served by Express/Nunjucks and a CLI-style importer subsystem that ingests TBX/TMX files into a JSON store.

##### File structure
- Top-level entry points:
- index.js (CLI entry)
- web/app.js (Express server)
- app/ → service layer (AppService.js)
- domain/ → core domain models (Term.js, User.js)
- importers/ → adapters for external data sources (arabeyes, microsoft, mozilla)
- store/ → persistence (in-memory + JSON files per source)
- web/ → presentation
- middlewares/ (domain-redirector)
- routes/ (Express controllers)
- views/ (Nunjucks templates + partials)
- public/ (static CSS, JS, fonts, images)
- tests/ → unit tests for domain objects

##### Key excerpts from README
- “قاموس رقمي إنجليزي - عربي…جمع المصطلحات من المشاريع مفتوحة المصدر…”
- Web-facing dictionary for technical translators and bloggers.

##### Main components
a. Frontend (Browser)
- HTTP client that requests pages & assets
b. Web Server (Express · Nunjucks)
- Middlewares (domain-redirector)
- Routes (index, search, term) → controllers
- View Renderer (Nunjucks templates)
- Static Asset Server (CSS, JS, fonts, images)
c. Application Service Layer (app/AppService.js)
- Coordinates domain & persistence
d. Domain Layer (domain/Term, domain/User)
- Business rules & entities
e. Persistence Layer (store)
- In-memory store abstraction (store/in-memory.js)
- JSON files for each source (store/terms-*.json)
f. Importer Subsystem (importers/*.js + index.js)
- CLI entry (index.js)
- Source adapters (arabeyes, microsoft, mozilla)
- TBX/TMX parsers (lang/*.tbx, .tmx)
- Loads data via AppService into JSON store
g. Tests (tests/*.test.js)
- Validate domain logic

##### Relationships & data flow
- User’s Browser → HTTP request → Express Middlewares → Route Handler → AppService → Domain Entities → Store → AppService → Nunjucks → HTTP response → Browser
- Import CLI → importers/index.js → each importer → parse TBX/TMX → AppService → Domain → Store → write JSON files

##### Architectural patterns & principles
- Layered (Presentation → Service → Domain → Repository)
- MVC-style for web routes & views
- Adapter pattern for importers
- File-based repository for quick bootstrapping (no external DB)
- Separation of concerns: import vs. serve

##### Relevant technologies
- Node.js, Express.js, Nunjucks
- JavaScript modules, Husky (git hooks), ESLint, Prettier
- JSON as storage format
- TBX/TMX language files

- Blue → runtime (web server, service)
- Green → data (store, JSON files)
- Orange → offline/CLI (importers)

##### Detail
- Folder as a component or sub-component
- Middleware before routes
- Nunjucks render step after service
- JSON files as the single source of truth

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Browser((Browser)):::external

    %% Web Server Layer
    subgraph "Web Server Layer"
        Express["Express Server"]:::runtime
        Middleware["Domain Redirector Middleware"]:::runtime
        IndexRoute["Index Route Controller"]:::runtime
        SearchRoute["Search Route Controller"]:::runtime
        TermRoute["Term Route Controller"]:::runtime
        ViewRenderer["Nunjucks View Renderer"]:::runtime
        StaticAssets["Static Asset Server"]:::runtime
    end

    %% Service & Domain Layer
    subgraph "Service & Domain Layer"
        AppService["AppService"]:::runtime
        TermEntity["Term Entity"]:::runtime
        UserEntity["User Entity"]:::runtime
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        InMemoryStore(("In-Memory Store")):::data
        JSONStore(("JSON Store Files")):::data
    end

    %% Importer Layer
    subgraph "Importer Layer"
        CLIEntry["CLI Entry"]:::cli
        ImporterIndex["Importer Adapters"]:::cli
        ArabeyesImporter["Arabeyes Importer"]:::cli
        MicrosoftImporter["Microsoft Importer"]:::cli
        MozillaImporter["Mozilla Importer"]:::cli
        Parsers["TBX/TMX Parsers"]:::external
    end

    %% Flow: Web Request
    Browser -->|HTTP Request| Express
    Express --> Middleware
    Middleware --> IndexRoute
    Middleware --> SearchRoute
    Middleware --> TermRoute
    IndexRoute --> AppService
    SearchRoute --> AppService
    TermRoute --> AppService
    AppService --> TermEntity
    AppService --> UserEntity
    TermEntity --> InMemoryStore
    TermEntity --> JSONStore
    AppService --> ViewRenderer
    ViewRenderer -->|HTML Response| Browser
    Express --> StaticAssets
    StaticAssets -->|Assets| Browser

    %% Flow: CLI Import
    CLIEntry --> ImporterIndex
    ImporterIndex --> ArabeyesImporter
    ImporterIndex --> MicrosoftImporter
    ImporterIndex --> MozillaImporter
    ArabeyesImporter --> Parsers
    MicrosoftImporter --> Parsers
    MozillaImporter --> Parsers
    Parsers --> AppService
    AppService --> TermEntity
    TermEntity --> InMemoryStore
    TermEntity --> JSONStore

    %% Click Events
    click StaticAssets "https://github.com/abdelaziz18003/mostalah/tree/main/web/public/"
    click ViewRenderer "https://github.com/abdelaziz18003/mostalah/tree/main/web/views/"
    click Express "https://github.com/abdelaziz18003/mostalah/blob/main/web/app.js"
    click Middleware "https://github.com/abdelaziz18003/mostalah/blob/main/web/middlewares/domain-redirector.js"
    click IndexRoute "https://github.com/abdelaziz18003/mostalah/blob/main/web/routes/index.js"
    click SearchRoute "https://github.com/abdelaziz18003/mostalah/blob/main/web/routes/search.js"
    click TermRoute "https://github.com/abdelaziz18003/mostalah/blob/main/web/routes/term.js"
    click AppService "https://github.com/abdelaziz18003/mostalah/blob/main/app/AppService.js"
    click TermEntity "https://github.com/abdelaziz18003/mostalah/blob/main/domain/Term.js"
    click UserEntity "https://github.com/abdelaziz18003/mostalah/blob/main/domain/User.js"
    click InMemoryStore "https://github.com/abdelaziz18003/mostalah/blob/main/store/in-memory.js"
    click JSONStore "https://github.com/abdelaziz18003/mostalah/blob/main/store/terms.js"
    click CLIEntry "https://github.com/abdelaziz18003/mostalah/blob/main/index.js"
    click ImporterIndex "https://github.com/abdelaziz18003/mostalah/blob/main/importers/index.js"
    click ArabeyesImporter "https://github.com/abdelaziz18003/mostalah/blob/main/importers/arabeyes-importer.js"
    click MicrosoftImporter "https://github.com/abdelaziz18003/mostalah/blob/main/importers/microsoft-importer.js"
    click MozillaImporter "https://github.com/abdelaziz18003/mostalah/blob/main/importers/mozilla-importer.js"
    click Parsers "https://github.com/abdelaziz18003/mostalah/blob/main/lang/microsoft.tbx"

    %% Styles
    classDef runtime fill:#D0E7FF,stroke:#0366d6;
    classDef data fill:#D0FFD7,stroke:#28a745;
    classDef cli fill:#FFE7D0,stroke:#d9750d;
    classDef external fill:#F0F0F0,stroke:#999;
```
