# ianhenderson/kstool architecture

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

- Interactive diagram: https://gitdiagram.com/ianhenderson/kstool
- Repository: https://github.com/ianhenderson/kstool

## Overview

##### Project type and purpose
- This is a full-stack web application (“Kanji Study Tool”) that provides flashcard-style Japanese character study.
- Front end: multiple Angular 1.x variants (plain Angular, Angular/E S6, Angular Material design) built as static assets under /public.
- Back end: Node.js + Express REST API, session middleware, SQLite database.

##### File structure
- Top level:
– public/…: three separate Angular front-end builds (angular-mat-design, angular, es6).
– server.js & server/: Express server entry point, configuration, routes, controllers, DB access, middleware.
– build.js, deploy.sh, .deployment, iisnode.yml: build & deploy scripts/config for Azure/IIS Node hosting.
– spec/: E2E/protractor & unit tests.

- server/ breakdown:
– config.js: server configuration (ports, DB path, session secrets)
– routes.js: REST endpoints (/login, /words, /session, etc.)
– controller.js: business logic for each endpoint
– db.js: SQLite wrapper, CRUD operations
– middleware.js & checkSession.js: authentication middleware

##### README for additional insights
- Confirms stack: Angular/UI-Router, Node/Express, SQLite.
- Flashcard workflow: client fetches one character + contextual words, then posts review results.

##### Main components & interactions
a. Components:
1. Static asset server – serves HTML, JS, CSS for Angular apps.
2. Angular SPA – UI modules (routes, directives, services) that render flashcards, handle login, settings.
3. Express API – HTTP endpoints for authentication, session management, word CRUD, review logic.
4. Middleware – session check, request logging, error handling.
5. SQLite database – persistent storage of users, words, review history.
6. Build/Deploy – scripts to lint, bundle, deploy to hosting (Azure/IIS Node).
7. Test harness – Jasmine (unit), Protractor (E2E).

b. Relationships & data flow:
– Client browser requests index.html → static asset server (Express static middleware).
– Angular app loads, UI-Router directs to views (home, add‐words, login, settings).
– Angular services call Express API endpoints (e.g., GET /api/word, POST /api/review).
– Express routes.js → middleware.checkSession → controller.js invokes db.js → SQLite.
– Controller returns JSON → Angular service processes response → UI updates.
– Build.js bundles source, deploy.sh pushes to hosting.
– Test suite targets both front end (Protractor) and back end (Jasmine).

c. Architectural patterns & principles:
– MVC on the server (routes → controllers → models/db).
– Component-based Angular 1.x (directives + services) with UI-Router for SPAs.
– Clear separation of concerns: static assets vs. API vs. persistence.
– Modular file structure supports swapping front-end themes (mat-design, ES6, plain).

d. Key technologies & libraries:
– Front end: Angular 1.x, UI-Router, Angular Material, custom directives & services.
– Back end: Node.js, Express, express-session, body-parser, sqlite3.
– Build/deploy: Node scripts, .deployment, iisnode.yml, nodemon.
– Testing: Jasmine, Protractor.

##### Detail without overcomplicating
– Capture every module-level boundary (static vs. dynamic, REST vs. session, build vs. runtime).
– Aim for a single cohesive view that shows all runtime interactions, plus an optional inset for build/test pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Browser["Client Browser"]:::external

    %% Static Asset Server
    subgraph "Static Asset Server" 
        Static["Express Static Middleware"]:::frontend
        click Static "https://github.com/ianhenderson/kstool/blob/master/server.js"
        Public["public/"]:::frontend
        click Public "https://github.com/ianhenderson/kstool/tree/master/public/"
    end

    %% Angular SPAs
    subgraph "Angular SPA Variants" 
        MAT["Material Design Variant"]:::frontend
        click MAT "https://github.com/ianhenderson/kstool/tree/master/public/angular-mat-design/"
        Plain["Plain Angular 1.x Variant"]:::frontend
        click Plain "https://github.com/ianhenderson/kstool/tree/master/public/angular/"
        ES6["ES6 Variant"]:::frontend
        click ES6 "https://github.com/ianhenderson/kstool/tree/master/public/es6/"
    end

    %% Express API Stack
    subgraph "Express API" 
        Routes["Routes (server/routes.js)"]:::backend
        click Routes "https://github.com/ianhenderson/kstool/blob/master/server/routes.js"
        Middleware["Middleware Layer"]:::backend
        click Middleware "https://github.com/ianhenderson/kstool/blob/master/server/middleware.js"
        CheckSession["Session Checker"]:::backend
        click CheckSession "https://github.com/ianhenderson/kstool/blob/master/server/checkSession.js"
        Controller["Controller (server/controller.js)"]:::backend
        click Controller "https://github.com/ianhenderson/kstool/blob/master/server/controller.js"
        Config["Configuration (server/config.js)"]:::backend
        click Config "https://github.com/ianhenderson/kstool/blob/master/server/config.js"
    end

    %% Database
    DB["SQLite Database (server/db.js)"]:::database
    click DB "https://github.com/ianhenderson/kstool/blob/master/server/db.js"

    %% Tooling
    subgraph "Build & Deploy" 
        Build["build.js"]:::tooling
        click Build "https://github.com/ianhenderson/kstool/blob/master/build.js"
        Deploy["deploy.sh"]:::tooling
        click Deploy "https://github.com/ianhenderson/kstool/blob/master/deploy.sh"
        DeployConfig[".deployment / iisnode.yml"]:::tooling
        click DeployConfig "https://github.com/ianhenderson/kstool/blob/master/.deployment"
        click DeployConfig "https://github.com/ianhenderson/kstool/blob/master/iisnode.yml"
    end

    subgraph "Test Suite" 
        ProtractorConf["protractor.conf.js"]:::tooling
        click ProtractorConf "https://github.com/ianhenderson/kstool/blob/master/spec/protractor.conf.js"
        ProtractorSpec["protractor.spec.js"]:::tooling
        click ProtractorSpec "https://github.com/ianhenderson/kstool/blob/master/spec/protractor.spec.js"
        DBSpec["db.spec.js"]:::tooling
        click DBSpec "https://github.com/ianhenderson/kstool/blob/master/spec/db.spec.js"
        TestsSpec["tests.spec.js"]:::tooling
        click TestsSpec "https://github.com/ianhenderson/kstool/blob/master/spec/tests.spec.js"
        JasmineConfig["jasmine.json"]:::tooling
        click JasmineConfig "https://github.com/ianhenderson/kstool/blob/master/spec/support/jasmine.json"
    end

    %% Flows
    Browser -->|HTTP GET index.html| Static
    Static -->|serves HTML/JS/CSS| MAT
    Static -->|serves HTML/JS/CSS| Plain
    Static -->|serves HTML/JS/CSS| ES6

    MAT -->|GET /api/*| Routes
    Plain -->|GET /api/*| Routes
    ES6 -->|GET /api/*| Routes

    Routes -->|calls| Middleware
    Middleware -->|checkSession| CheckSession
    Middleware -->|proceed| Controller
    Routes -->|bypass auth| Controller

    Controller -->|query/update| DB
    DB -->|results| Controller
    Controller -->|response JSON| Routes

    Routes -->|JSON response| MAT
    Routes -->|JSON response| Plain
    Routes -->|JSON response| ES6

    %% Tooling flows
    Build -->|bundles frontend/backend| Public
    Deploy -->|deploys| Public
    Deploy -->|deploys| Static
    ProtractorConf -->|e2e tests| MAT
    ProtractorConf -->|e2e tests| Plain
    ProtractorConf -->|e2e tests| ES6
    DBSpec -->|unit tests| Controller
    TestsSpec -->|unit tests| Middleware

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef backend fill:#DFFFE0,stroke:#008000,color:#004d00;
    classDef database fill:#FFEFD5,stroke:#FF8C00,color:#8B4513,shape:cylinder;
    classDef tooling fill:#F0F0F0,stroke:#888888,color:#555555;
    classDef external fill:#FFFFFF,stroke:#AAAAAA,color:#333333;
```
