# aymanenahji/connectsline architecture

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

- Interactive diagram: https://gitdiagram.com/aymanenahji/connectsline
- Repository: https://github.com/aymanenahji/connectsline

## Overview

##### Project type and purpose
- This is a full-stack, server-side rendered web application built on Express.js and Handlebars.
- It serves static assets (CSS, JS, images) from a public folder, renders dynamic pages via HBS templates (layouts + partials), and enhances interactivity with HTMX, Alpine.js, and AOS.
- It includes a contact form that uses Joi for validation and likely sends emails via an external service (configured by environment variables).

##### File structure
- Top level:
- server.js: Express application entry point
- package.json / .env.example / .eslintrc.json / tailwind.config.js / postcss.config.js / vercel.json
- public/: static assets (css, js, images, locales)
- views/: HBS templates organized into layouts/, partials/, plus feature folders (telemarketing/, web/) and standalone pages (index.hbs, contact.hbs)
- Patterns:
- MVC-like separation: server.js handles routing/controllers, views/ holds presentation logic
- Modular layout via Handlebars partials
- HTMX endpoints likely return fragment partials
- Tailwind CSS build/watch, plus postcss config
- Environment config via dotenv

##### Extract key architecture notes from the README
- Technologies: Express.js (web framework), Handlebars (templating), Tailwind CSS (styling), HTMX & Alpine.js (dynamic behavior), Joi (validation), dotenv (config)
- The app is production-ready, supports localization (public/locales/*.json), dark mode, responsive design, animated sections (AOS).

a. Main components
1. Client (Browser)
- Renders HTML/CSS/JS
- Issues initial page requests & HTMX/XHR calls
2. CDN/Static Asset Server
- Serves CSS (Tailwind, AOS), JS (HTMX, translations.js, AOS script), images, locale JSON
3. Express.js Application
- Router layer
- Controller handlers
- Joi validation middleware
- HBS rendering engine (layouts + partials + pages)
- dotenv configuration loader
4. External Services
- Email/SMS API (for contact form)
- Social media links (configured via env vars)
5. Deployment Environment
- Vercel / Node.js runtime
- Tailwind watcher in dev, static build in prod

b. Relationships & data flows
- Browser → HTTP(S) GET → Express Router → Controller → HBS → HTML → Browser
- Browser GET /public/* → Static Asset Server → CSS/JS/images/locales → Browser
- Browser (HTMX) → HTTP(S) POST /partial-endpoint → Router → Joi Validation → Partial HBS → JSON/HTML fragment → Browser
- Browser submits contact form → Router → Joi → External Email API → 200/400 response → Browser
- dotenv loads company info & API keys at server startup

c. Architectural patterns & design principles
- MVC-like separation: routing/controllers vs presentation (views)
- Modular partials for reusability (nav-bar, footer, contact form, etc.)
- Progressive enhancement: core HTML via HBS, dynamic updates via HTMX & Alpine.js
- Asset pipeline: Tailwind CSS → postcss → public/css; bundling minimal JS for performance
- Localization: JSON files in public/locales served statically

d. Key technologies/frameworks
- Express.js: HTTP server & routing
- Handlebars: template engine (layouts + partials)
- Tailwind CSS & PostCSS: styling and build process
- HTMX & Alpine.js: client-side interactivity
- AOS: scroll animations
- Joi: schema validation for form input
- dotenv: environment variable management

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Side
    subgraph "Client Side" 
        direction TB
        Browser["Browser"]:::frontend
        Browser -->|"GET /pages"| Router
        Browser -->|"GET /public/*"| StaticAssets
        Browser -->|"HTMX XHR"| Router
        Browser -->|"Submit Form"| Router
    end

    %% Static Assets
    subgraph "Static Assets" 
        direction TB
        StaticAssets["Public Folder"]:::frontend
        CSS["CSS (public/css/)"]:::frontend
        JS["JavaScript (public/js/)"]:::frontend
        Images["Images (public/images/)"]:::frontend
        Locales["Locales (public/locales/)"]:::frontend
        StaticAssets --> CSS
        StaticAssets --> JS
        StaticAssets --> Images
        StaticAssets --> Locales
    end

    %% Server Side
    subgraph "Server Side" 
        direction TB
        ExpressApp["Express.js App (server.js)"]:::backend
        Config["dotenv Config (.env.example)"]:::backend
        Package["package.json"]:::backend
        Router["Router & Controllers"]:::backend
        Joi["Joi Validation Middleware"]:::backend
        Hbs["HBS Rendering Engine"]:::backend
        Layouts["HBS Layouts (views/layouts/main.hbs)"]:::backend
        Partials["HBS Partials (views/partials/)"]:::backend
        Pages["Pages (views/*.hbs)"]:::backend
        Telemarketing["Telemarketing Views (views/telemarketing/)"]:::backend
        WebServices["Web Services Views (views/web/)"]:::backend

        ExpressApp --> Config
        ExpressApp --> Package
        ExpressApp --> Router
        Router --> Joi
        Router --> Hbs
        Hbs --> Layouts
        Hbs --> Partials
        Hbs --> Pages
        Pages --> Telemarketing
        Pages --> WebServices
    end

    %% External Services
    subgraph "External Services"
        direction TB
        EmailAPI["Email/SMS API"]:::external
        SocialLinks["Social Links Config"]:::external
    end

    %% Deployment & Build
    subgraph "Deployment & Build"
        direction TB
        Vercel["Vercel Deployment (vercel.json)"]:::infra
        TailwindWatch["Tailwind Watcher (tailwind.config.js)"]:::infra
        PostCSS["PostCSS Config (postcss.config.js)"]:::infra
        ExpressApp --> Vercel
        ExpressApp --> TailwindWatch
        TailwindWatch --> PostCSS
    end

    %% Data Flows
    Router -->|"Validate & Process Form"| EmailAPI
    Router -->|"Return HTMX Fragment"| Partials
    Router -->|"Render Page"| Hbs
    Router -->|"Serve Assets"| StaticAssets

    %% Click Events
    click ExpressApp "https://github.com/aymanenahji/connectsline/blob/main/server.js"
    click Config "https://github.com/aymanenahji/connectsline/blob/main/.env.example"
    click Package "https://github.com/aymanenahji/connectsline/blob/main/package.json"
    click TailwindWatch "https://github.com/aymanenahji/connectsline/blob/main/tailwind.config.js"
    click PostCSS "https://github.com/aymanenahji/connectsline/blob/main/postcss.config.js"
    click Vercel "https://github.com/aymanenahji/connectsline/blob/main/vercel.json"
    click Layouts "https://github.com/aymanenahji/connectsline/blob/main/views/layouts/main.hbs"
    click Partials "https://github.com/aymanenahji/connectsline/tree/main/views/partials/"
    click Pages "https://github.com/aymanenahji/connectsline/blob/main/views/index.hbs"
    click Pages "https://github.com/aymanenahji/connectsline/blob/main/views/contact.hbs"
    click Pages "https://github.com/aymanenahji/connectsline/blob/main/views/portfolio.hbs"
    click Telemarketing "https://github.com/aymanenahji/connectsline/tree/main/views/telemarketing/"
    click WebServices "https://github.com/aymanenahji/connectsline/tree/main/views/web/"
    click CSS "https://github.com/aymanenahji/connectsline/tree/main/public/css/"
    click JS "https://github.com/aymanenahji/connectsline/tree/main/public/js/"
    click Images "https://github.com/aymanenahji/connectsline/tree/main/public/images/"
    click Locales "https://github.com/aymanenahji/connectsline/tree/main/public/locales/"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#0097A7,color:#006064
    classDef backend fill:#E8F5E9,stroke:#388E3C,color:#1B5E20
    classDef external fill:#FFF3E0,stroke:#FB8C00,color:#E65100
    classDef infra fill:#ECEFF1,stroke:#455A64,color:#263238
```
