# ccoenraets/cordova-tutorial architecture

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

- Interactive diagram: https://gitdiagram.com/ccoenraets/cordova-tutorial
- Repository: https://github.com/ccoenraets/cordova-tutorial

## Overview

##### Project Type & Purpose
- This is an Apache Cordova (hybrid) mobile-app tutorial that teaches how to build an Employee Directory SPA (Single Page Application) using HTML/CSS/JS.
- The project also includes a small Node.js/Express server exposing a REST endpoint (`/employees`) to serve JSON employee data.
- Multiple “solutions” folders (part05→part11, directory-backbone) show progressive enhancements; the “starter-www” folder is the base client.

##### File Structure & Architectural Patterns
Top-level directories:
- server/ – Node.js/Express REST API
– server.js (app entry), routes/employees.js
- starter-www/ – Base Cordova client (HTML, CSS, JS, libs)
- solutions/ – Versioned client implementations (parts 05–11, directory-backbone)
Patterns & layers in each client folder:
- index.html – single page shell
- lib/ – third-party libs (jQuery, Handlebars, FastClick, Pageslider, Backbone in some solutions)
- js/ – application code:
– app.js – bootstrap & Cordova “deviceready” handler
– router.js – in-app navigation (pushState/pageslider)
– services/ – data-access adapters (json, localstorage, memory, websql)
– views/ & models.js or EmployeeView.js, EmployeeListView.js – UI MVC/MV* components
- Service abstraction layer lets you switch storage backends.

a. Main Components
1. Cordova Container / WebView (hosted on device)
2. UI Layer
- Templates & Views (Handlebars)
- Router & Navigation (pageslider.js, custom router)
3. Service Layer (data-access)
- JSONService → HTTP calls to Server API
- LocalStorageService → browser localStorage
- WebSQLService → HTML5 WebSQL DB
- MemoryService → in‐memory cache
4. Server (Node.js/Express)
- /employees API endpoint
5. Third-party Libraries
- jQuery, FastClick, Pageslider, Handlebars, Ratchet/Topcoat, Backbone (in directory-backbone solution)
b. Relationships & Data Flows
- User taps in UI → Router updates View
- View calls Service Layer → selects appropriate EmployeeService implementation
- JSONService sends AJAX → Node.js server → responds with JSON
- LocalStorage/WebSQL services read/write on device
- Data returned to View → Handlebars templates → rendered UI
c. Architectural Patterns & Principles
- Single-Page Architecture (SPA) – no page reloads
- MV* structure (in Backbone solutions) or light MVC with views/models
- Service‐oriented abstraction for pluggable storage backends
- Cordova plugin/event model (deviceready event)
d. Key Technologies & Frameworks
- Apache Cordova (WebView container)
- Node.js + Express (server)
- jQuery, Handlebars, FastClick, Pageslider, Ratchet/Topcoat, Backbone.js
- HTML5 WebSQL, localStorage

##### Capturing Essential Architectural Elements
- Be sure to include the Cordova WebView boundary.
- Service abstraction with pluggable backends.
- Cordova’s `deviceready` event bootstrapping the app.
- REST API boundary and the ability to swap to local/offline storage.
- Don’t overload with every file; group by logical layers (assets, libs, js modules).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Tier
    subgraph "Client (Cordova App)"
        direction TB
        CordovaWebView["Cordova WebView"]:::client
        App["app.js\n(deviceready)"]:::client
        Shell["index.html\n(SPA Shell)"]:::client
        Router["Router & Navigation"]:::client
        subgraph "Templates & Views"
            direction TB
            EmpListView["EmployeeListView"]:::client
            EmpView["EmployeeView"]:::client
            HomeView["HomeView"]:::client
            Models["models.js"]:::client
        end
        subgraph "Service Layer" 
            direction TB
            JSONService["JSONService\n(HTTP)"]:::service
            LocalService["LocalStorageService"]:::service
            WebSQLService["WebSQLService"]:::service
            MemoryService["MemoryService"]:::service
        end
        subgraph "Third-Party Libraries"
            direction TB
            jQuery["jQuery"]:::lib
            Handlebars["Handlebars"]:::lib
            FastClick["FastClick"]:::lib
            Pageslider["Pageslider"]:::lib
            Backbone["Backbone.js"]:::lib
        end
    end

    %% Server Tier
    subgraph "Server (Node.js/Express)"
        direction TB
        ServerApp["server.js\n(Express App)"]:::server
        EmployeesRoute["/employees Route"]:::server
        DataSource["Data Source\n(JSON/In-Memory)"]:::server
    end

    %% Data Flows
    CordovaWebView -->|boots on deviceready| App
    App -->|loads shell| Shell
    App -->|initializes| Router
    Router -->|renders| EmpListView
    EmpListView -->|uses| Templates & Views
    EmpListView -->|calls| JSONService
    EmpView -->|calls| JSONService
    HomeView -->|calls| JSONService

    JSONService -->|AJAX /employees| EmployeesRoute
    EmployeesRoute -->|reads| DataSource
    DataSource -->|responds JSON| EmployeesRoute
    EmployeesRoute -->|JSON response| JSONService

    LocalService -->|read/write| DataSource
    WebSQLService -->|read/write| DataSource
    MemoryService -->|cache| DataSource

    JSONService -->|uses| jQuery
    JSONService -->|templating| Handlebars
    App -->|fast clicks| FastClick
    Router -->|page slide| Pageslider
    EmpListView -->|MV*| Backbone

    %% Click Events
    click ServerApp "https://github.com/ccoenraets/cordova-tutorial/blob/master/server/server.js"
    click EmployeesRoute "https://github.com/ccoenraets/cordova-tutorial/blob/master/server/routes/employees.js"
    click App "https://github.com/ccoenraets/cordova-tutorial/blob/master/starter-www/js/app.js"
    click Shell "https://github.com/ccoenraets/cordova-tutorial/blob/master/starter-www/index.html"
    click Router "https://github.com/ccoenraets/cordova-tutorial/blob/master/starter-www/lib/router.js"
    click JSONService "https://github.com/ccoenraets/cordova-tutorial/blob/master/starter-www/js/services/json/EmployeeService.js"
    click LocalService "https://github.com/ccoenraets/cordova-tutorial/blob/master/starter-www/js/services/localstorage/EmployeeService.js"
    click WebSQLService "https://github.com/ccoenraets/cordova-tutorial/blob/master/starter-www/js/services/websql/EmployeeService.js"
    click MemoryService "https://github.com/ccoenraets/cordova-tutorial/blob/master/starter-www/js/services/memory/EmployeeService.js"
    click EmpListView "https://github.com/ccoenraets/cordova-tutorial/blob/master/solutions/directory-backbone/js/EmployeeListView.js"
    click EmpView "https://github.com/ccoenraets/cordova-tutorial/blob/master/solutions/directory-backbone/js/EmployeeView.js"
    click HomeView "https://github.com/ccoenraets/cordova-tutorial/blob/master/solutions/directory-backbone/js/HomeView.js"
    click Models "https://github.com/ccoenraets/cordova-tutorial/blob/master/solutions/directory-backbone/js/models.js"
    click jQuery "https://github.com/ccoenraets/cordova-tutorial/blob/master/starter-www/lib/jquery.js"
    click Handlebars "https://github.com/ccoenraets/cordova-tutorial/blob/master/starter-www/lib/handlebars.js"
    click FastClick "https://github.com/ccoenraets/cordova-tutorial/blob/master/starter-www/lib/fastclick.js"
    click Pageslider "https://github.com/ccoenraets/cordova-tutorial/blob/master/starter-www/lib/pageslider.js"
    click Backbone "https://github.com/ccoenraets/cordova-tutorial/blob/master/solutions/directory-backbone/lib/backbone.js"

    %% Styles
    classDef client fill:#D0E6FF,stroke:#004A99,color:#000;
    classDef service fill:#DFF2D8,stroke:#3C763D,color:#000;
    classDef lib fill:#E8E8E8,stroke:#666,color:#000;
    classDef server fill:#FFE5CC,stroke:#CC5200,color:#000;
```
