# maxepunk/alntool architecture

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

- Interactive diagram: https://gitdiagram.com/maxepunk/alntool
- Repository: https://github.com/maxepunk/alntool

## Overview

##### Project type and purpose
- This is a full-stack web application (“StoryForge”) that reads narrative data from Notion, exposes it via a Node/Express backend API, and visualizes it in a React frontend.
- The sample data under SampleNotionData (characters, elements, puzzles, timelines CSV/MD files) confirm that the system’s domain is “story world-building” based on Notion databases.

##### File structure
- Top-level
- package.json + node_modules – possibly a root workspace orchestrator or placeholder.
- SampleNotionData/… – local CSV/MD exports for development or testing.
- storyforge/ – contains the actual monorepo.
- storyforge/backend
- .env / .env.example / .env.test – environment variables for Notion API credentials, test database or mocks.
- src/controllers/notionController.js – HTTP handlers.
- src/services/notionService.js – Notion API client logic.
- src/utils/notionPropertyMapper.js – maps Notion’s property schemas to the app’s domain model.
- src/routes/notion.js – routes for characters, elements, puzzles, timelines.
- tests/… – Jest unit, integration, and utils tests with coverage artifacts.
- storyforge/frontend
- index.html + dist/… – compiled React app assets.
- src (inferred) – though not shown, tests indicate pure functions, hooks, and components are under test.
- babel.config.cjs, jest.config.cjs – transpilation and test setup.

##### README for additional insights
- The provided README focuses on frontend testing configuration: colocated tests, transforming ES modules, testing hooks/components, running `npm test`.

##### Final recommendations
- Be very detailed: show the controller→service→utils chain within the backend.
- Both development and production modes (i.e., sample data vs. real Notion).
- Do not over-compartmentalize; separate into these logical components and highlight their interactions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External and Dev/Test Data
    subgraph "Dev/Test Data" 
        direction TB
        SN["SampleNotionData (CSV/MD files)"]:::data
    end

    %% External Service
    NA["Notion API"]:::external

    %% Backend Service
    subgraph "Backend Service (Node.js + Express)" 
        direction TB
        BE_INDEX["Entry Point\nsrc/index.js"]:::service
        BE_ROUTES["API Routes\nsrc/routes/notion.js"]:::service
        BE_CONTROLLER["Controllers\nsrc/controllers/notionController.js"]:::service
        BE_SERVICE["Services\nsrc/services/notionService.js"]:::service
        BE_UTILS["Utils\nsrc/utils/notionPropertyMapper.js"]:::service
    end

    %% Frontend Client
    subgraph "Frontend Client (React SPA)" 
        direction TB
        FE_HTML["index.html"]:::service
        FE_DIST["Bundled Assets\ndist/"]:::service
    end

    %% CI and Testing
    subgraph "CI & Testing" 
        direction TB
        JB_BE["Backend Jest Tests\ntests/"]:::test
        JB_BE_CFG["jest.config.js"]:::test
        BE_COV["Coverage Reports\ncoverage/"]:::test
        JB_FE_CFG["Frontend Jest Config\nbabel.config.cjs\njest.config.cjs"]:::test
    end

    %% Relationships
    FE_HTML -->|"serves SPA"| FE_DIST
    FE_DIST -->|"HTTP requests"| BE_INDEX
    BE_INDEX -->|"mounts routes"| BE_ROUTES
    BE_ROUTES -->|"invokes"| BE_CONTROLLER
    BE_CONTROLLER -->|"calls"| BE_SERVICE
    BE_SERVICE -->|"maps via"| BE_UTILS
    BE_SERVICE -->|"REST API calls"| NA
    BE_SERVICE -->|"falls back (dev/test)"| SN
    JB_BE -->|"runs tests on"| BE_CONTROLLER
    JB_BE -->|"runs tests on"| BE_SERVICE
    JB_BE -->|"runs tests on"| BE_UTILS
    JB_BE -->|"uses config"| JB_BE_CFG
    JB_BE -->|"generates"| BE_COV
    JB_FE_CFG -->|"configures tests for"| FE_DIST

    %% Click Events
    click SN "https://github.com/maxepunk/alntool/tree/master/SampleNotionData/"
    click BE_INDEX "https://github.com/maxepunk/alntool/blob/master/storyforge/backend/src/index.js"
    click BE_ROUTES "https://github.com/maxepunk/alntool/blob/master/storyforge/backend/src/routes/notion.js"
    click BE_CONTROLLER "https://github.com/maxepunk/alntool/blob/master/storyforge/backend/src/controllers/notionController.js"
    click BE_SERVICE "https://github.com/maxepunk/alntool/blob/master/storyforge/backend/src/services/notionService.js"
    click BE_UTILS "https://github.com/maxepunk/alntool/blob/master/storyforge/backend/src/utils/notionPropertyMapper.js"
    click JB_BE "https://github.com/maxepunk/alntool/tree/master/storyforge/backend/tests/"
    click JB_BE_CFG "https://github.com/maxepunk/alntool/blob/master/storyforge/backend/jest.config.js"
    click BE_COV "https://github.com/maxepunk/alntool/tree/master/storyforge/backend/coverage/"
    click FE_HTML "https://github.com/maxepunk/alntool/blob/master/storyforge/frontend/index.html"
    click FE_DIST "https://github.com/maxepunk/alntool/tree/master/storyforge/frontend/dist/"
    click JB_FE_CFG "https://github.com/maxepunk/alntool/blob/master/storyforge/frontend/jest.config.cjs"

    %% Styles
    classDef service fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef external fill:#DFFFD8,stroke:#28a745,color:#28a745;
    classDef data fill:#F0F0F0,stroke:#6a737d,color:#6a737d;
    classDef test fill:#FFF5D1,stroke:#dbab09,color:#8a6d1b;
```
