# herol3oy/austen architecture

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

- Interactive diagram: https://gitdiagram.com/herol3oy/austen
- Repository: https://github.com/herol3oy/austen

## Overview

##### Project Type & Purpose
- The application offers both client-side (Angular UI with Angular Material and component-based pages) and server-side functionalities (server routes, middleware for authentication, and API endpoints).

##### File Structure
- Top-level configuration files (e.g., angular.json, package.json, tsconfig files, etc.) indicate an Angular project with a custom setup using Analog for server-side rendering.
- Additional folders (public, screenshots) serve static assets and UI references.

##### Key Components
a. Frontend (Angular Client):
- Core Angular Application:
- Entry points: main.ts and main.server.ts.
- App components and configuration: app.component, app.config.ts, and app.config.server.ts.
- UI Layer:
- Components: Various UI components like topbar, graph card, confirm dialog.
- Pages: Auth pages (login), Home, About, Countries, Discover, My Graphs, etc.
- Service Layer on the Client:
- Styling & Assets:
- Global styles (styles.scss) and other assets like index.html and content in the public folder.

b. Backend / Server:
- API Endpoints:
- Under “src/server/routes/v1”: Routes like getMermaidSyntax.ts that process requests.
- Middleware:
- Authentication (auth.ts) that manages access to routes.
- Integration with Supabase:
- Interaction with Supabase (src/server/supabase.ts) to store and retrieve graph data.

c. External Services & APIs:
- External APIs:
- Open Library for book search.
- DeepSeek and OpenAI for AI-powered character analysis.
- Database:
- Supabase is used as the primary datastore (graphs table with fields for id, book_name, author_name, svg_graph, mermaid_syntax, emojis, user_id, is_public, created_at) as described in the README.
- Deployment & Hosting:
- Cloudflare Pages is mentioned as part of the stack for hosting.

##### Relationships & Interactions
- The Angular client interacts with the server backend through well-defined API endpoints. For instance, when generating a graph, the client calls an endpoint (e.g., getMermaidSyntax) which in turn may query Supabase or trigger an AI analysis.
- The services in the Angular app encapsulate calls to external APIs (Open Library, DeepSeek, OpenAI) to retrieve book data and AI results.
- The server side uses middleware (auth.ts) to secure its APIs before data or AI processing is handled.
- The design should clearly illustrate data flow: from user actions in the UI to service calls, API backend processing, and storage/retrieval in Supabase.

##### Architectural Patterns & Elements to Highlight
- Separation between the client (Angular frontend) and the server (API routes, middleware). This separation is key in a full-stack application.
- How Angular modules and components follow a modular UI design pattern.
- How external services and APIs integrate with both the frontend and backend, serving as crucial pillars of functionality.
- Mention that both server-side rendering (SSR using Analog) and API-driven interactions are part of the system’s design.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Angular Frontend"
        %% Entry Points
        subgraph "Entry Points"
            FE_ENTRY["Frontend Entry (main.ts)"]
            FE_SSR["Frontend SSR Entry (main.server.ts)"]
        end
        %% App Components & Configuration
        subgraph "App Components & Configuration"
            APP_COMP["App Component (app.component.ts)"]
            APP_CONF["App Config (app.config.ts)"]
            APP_CONF_SSR["Server App Config (app.config.server.ts)"]
        end
        %% UI Components
        subgraph "UI Components"
            UI_TOPBAR["Topbar Component"]
            UI_GRAPHCARD["Graph Card Component"]
            UI_CONFIRM["Confirm Dialog Component"]
        end
        %% Pages
        subgraph "Pages"
            PAGE_LOGIN["Auth Login Page (client)"]
            PAGE_LOGIN_SSR["Auth Login SSR Page"]
            PAGE_HOME["Home Page"]
            PAGE_ABOUT["About Page"]
            PAGE_COUNTRIES["Countries Page"]
            PAGE_COUNTRIES_SSR["Countries SSR Page"]
            PAGE_DISCOVER["Discover Page"]
            PAGE_MYGRAPHS["My Graphs Page"]
            PAGE_DYNAMIC["Dynamic Page"]
        end
        %% Client Service Layer
        subgraph "Client Service Layer"
            SVC_AUTH["Auth Service"]
            SVC_CLIP["Clipboard Service"]
            SVC_DOWNLOAD["Download Service"]
            SVC_LOADING["LoadingState Service"]
            SVC_MERMAID["Mermaid Service"]
            SVC_OPENLIB["OpenLib Service"]
            SVC_SUPABASE["Supabase Service"]
        end
        %% Static & Assets
        subgraph "Static & Assets"
            STATIC_INDEX["Index HTML"]
            STATIC_PUBLIC["Public Assets"]
            STATIC_STYLES["Global Styles"]
        end
    end

    subgraph "Backend / Server"
         BACKEND_AUTH["Authentication Middleware"]
         BACKEND_API["Mermaid Syntax API"]
         BACKEND_SUPA["Supabase Integration"]
    end

    subgraph "External Services"
         EXT_SUPA_DB["Supabase Database"]
         EXT_OPEN_LIB["Open Library API"]
         EXT_DEEPSEEK["DeepSeek API"]
         EXT_OPEN_AI["OpenAI API"]
         EXT_CLOUDFLARE["Cloudflare Pages"]
    end

    %% Data Flow Connections
    PAGE_HOME -->|"calls"| SVC_MERMAID
    SVC_MERMAID -->|"generates"| BACKEND_API
    BACKEND_AUTH ---|"protects"| BACKEND_API
    BACKEND_API -->|"stores"| BACKEND_SUPA
    BACKEND_SUPA -->|"CRUD"| EXT_SUPA_DB
    BACKEND_API -->|"fetches"| EXT_OPEN_LIB
    BACKEND_API -->|"analyzes"| EXT_DEEPSEEK
    BACKEND_API -->|"supports"| EXT_OPEN_AI
    STATIC_INDEX -->|"hosts"| FE_ENTRY
    STATIC_PUBLIC -->|"serves"| FE_ENTRY
    PAGE_LOGIN -->|"authenticates"| SVC_AUTH
    SVC_AUTH -->|"validates"| BACKEND_AUTH
    UI_TOPBAR -->|"navigatesTo"| PAGE_HOME
    UI_GRAPHCARD -->|"displays"| PAGE_DYNAMIC
    FE_ENTRY -->|"deployedOn"| EXT_CLOUDFLARE

    %% Click Events
    click FE_ENTRY "https://github.com/herol3oy/austen/blob/main/src/main.ts"
    click FE_SSR "https://github.com/herol3oy/austen/blob/main/src/main.server.ts"
    click APP_COMP "https://github.com/herol3oy/austen/blob/main/src/app/app.component.ts"
    click APP_CONF "https://github.com/herol3oy/austen/blob/main/src/app/app.config.ts"
    click APP_CONF_SSR "https://github.com/herol3oy/austen/blob/main/src/app/app.config.server.ts"
    click UI_TOPBAR "https://github.com/herol3oy/austen/blob/main/src/app/components/topbar.component.ts"
    click UI_GRAPHCARD "https://github.com/herol3oy/austen/blob/main/src/app/components/graph-card.component.ts"
    click UI_CONFIRM "https://github.com/herol3oy/austen/blob/main/src/app/components/confirm-dialog.component.ts"
    click PAGE_LOGIN "https://github.com/herol3oy/austen/blob/main/src/app/pages/(auth)/login.page.ts"
    click PAGE_LOGIN_SSR "https://github.com/herol3oy/austen/blob/main/src/app/pages/(auth)/login.server.ts"
    click PAGE_HOME "https://github.com/herol3oy/austen/blob/main/src/app/pages/(home).page.ts"
    click PAGE_ABOUT "https://github.com/herol3oy/austen/blob/main/src/app/pages/about.page.ts"
    click PAGE_COUNTRIES "https://github.com/herol3oy/austen/blob/main/src/app/pages/countries.page.ts"
    click PAGE_COUNTRIES_SSR "https://github.com/herol3oy/austen/blob/main/src/app/pages/countries.server.ts"
    click PAGE_DISCOVER "https://github.com/herol3oy/austen/blob/main/src/app/pages/discover.page.ts"
    click PAGE_MYGRAPHS "https://github.com/herol3oy/austen/blob/main/src/app/pages/my-graphs.page.ts"
    click PAGE_DYNAMIC "https://github.com/herol3oy/austen/blob/main/src/app/pages/[id].page.ts"
    click SVC_AUTH "https://github.com/herol3oy/austen/blob/main/src/app/services/auth.service.ts"
    click SVC_CLIP "https://github.com/herol3oy/austen/blob/main/src/app/services/clipboard.service.ts"
    click SVC_DOWNLOAD "https://github.com/herol3oy/austen/blob/main/src/app/services/download.service.ts"
    click SVC_LOADING "https://github.com/herol3oy/austen/blob/main/src/app/services/loadingState.service.ts"
    click SVC_MERMAID "https://github.com/herol3oy/austen/blob/main/src/app/services/mermaid.service.ts"
    click SVC_OPENLIB "https://github.com/herol3oy/austen/blob/main/src/app/services/openlib.service.ts"
    click SVC_SUPABASE "https://github.com/herol3oy/austen/blob/main/src/app/services/supabase.service.ts"
    click BACKEND_AUTH "https://github.com/herol3oy/austen/blob/main/src/server/middleware/auth.ts"
    click BACKEND_API "https://github.com/herol3oy/austen/blob/main/src/server/routes/v1/getMermaidSyntax.ts"
    click BACKEND_SUPA "https://github.com/herol3oy/austen/blob/main/src/server/supabase.ts"
    click STATIC_INDEX "https://github.com/herol3oy/austen/blob/main/index.html"
    click STATIC_PUBLIC "https://github.com/herol3oy/austen/tree/main/public"
    click STATIC_STYLES "https://github.com/herol3oy/austen/blob/main/src/styles.scss"

    %% Style Classes
    classDef frontend fill:#cfe2f3,stroke:#084298,stroke-width:2px;
    classDef backend fill:#d1e7dd,stroke:#0f5132,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#842029,stroke-width:2px;

    class FE_ENTRY,FE_SSR,APP_COMP,APP_CONF,APP_CONF_SSR,UI_TOPBAR,UI_GRAPHCARD,UI_CONFIRM,PAGE_LOGIN,PAGE_LOGIN_SSR,PAGE_HOME,PAGE_ABOUT,PAGE_COUNTRIES,PAGE_COUNTRIES_SSR,PAGE_DISCOVER,PAGE_MYGRAPHS,PAGE_DYNAMIC,SVC_AUTH,SVC_CLIP,SVC_DOWNLOAD,SVC_LOADING,SVC_MERMAID,SVC_OPENLIB,SVC_SUPABASE,STATIC_INDEX,STATIC_PUBLIC,STATIC_STYLES frontend;
    class BACKEND_AUTH,BACKEND_API,BACKEND_SUPA backend;
    class EXT_SUPA_DB,EXT_OPEN_LIB,EXT_DEEPSEEK,EXT_OPEN_AI,EXT_CLOUDFLARE external;
```
