# hekimaconstant/storyforge architecture

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

- Interactive diagram: https://gitdiagram.com/hekimaconstant/storyforge
- Repository: https://github.com/hekimaconstant/storyforge

## Overview

This is a Flask story-creation and sharing application. Users browse stories, register or log in, generate a story from a genre, topic, and instructions, then can publish it and view or download stories. Other documented-in-code capabilities include profiles and avatars, story deletion, and TXT/DOCX/PDF export. The graph distinguishes the Flask route layer, story-generation services, persistence, and presentation. Source excerpts show the main generation calls and database access; several route details and template connections are only partially sampled, so those links are omitted rather than inferred.

Main entry points: [`app.py`](https://github.com/hekimaconstant/storyforge/blob/main/app.py) (Flask routes), [`services/story_service.py`](https://github.com/hekimaconstant/storyforge/blob/main/services/story_service.py) (Story service), [`database/db.py`](https://github.com/hekimaconstant/storyforge/blob/main/database/db.py) (Database adapter), [`static/js/profile.js`](https://github.com/hekimaconstant/storyforge/blob/main/static/js/profile.js) (Avatar interaction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_flask["Flask routes<br/>[app.py]"]
  node_accounts["Accounts<br/>[app.py]"]
  node_story_browse["Story browsing<br/>[app.py]"]
  node_story_publish["Story publishing<br/>[app.py]"]
  node_story_view["Story viewing<br/>[app.py]"]
  node_story_export["Story export<br/>[app.py]"]
  node_profile["Profiles and avatars<br/>[app.py]"]
  node_about["About and contact<br/>[about_us.html]"]
  node_exporter["Document exporters<br/>[exporter.py]"]
end

subgraph group_generation["Story generation"]
  node_story_service["Story service<br/>[story_service.py]"]
  node_prompt_builder["Prompt builder<br/>[prompt_builder.py]"]
  node_ai_service["AI generation<br/>[hf_service.py]"]
  node_thumbnail["Thumbnail URLs"]
end

subgraph group_persistence["Persistence"]
  node_db_adapter["Database adapter<br/>[db.py]"]
  node_database[("Story and user data<br/>[schema.sql]")]
end

subgraph group_presentation["Presentation"]
  node_templates["Page templates"]
  node_profile_js["Avatar interaction<br/>[profile.js]"]
  node_view_story_js["Story-page interaction<br/>[view_story.js]"]
  node_about_js["Contact interaction<br/>[about_us.js]"]
end

node_visitor(("Visitor"))

node_visitor -->|"uses"| node_flask
node_flask -->|"routes"| node_accounts
node_flask -->|"routes"| node_story_browse
node_flask -->|"routes"| node_story_publish
node_flask -->|"routes"| node_story_view
node_flask -->|"routes"| node_story_export
node_flask -->|"routes"| node_profile
node_flask -->|"queries"| node_db_adapter
node_story_publish -->|"generates"| node_story_service
node_story_service -->|"builds prompt"| node_prompt_builder
node_story_service -->|"requests story"| node_ai_service
node_flask -.->|"uses"| node_thumbnail
node_story_export -.->|"formats files"| node_exporter
node_db_adapter -.->|"reads and writes"| node_database
node_flask -.->|"renders pages"| node_templates
node_profile_js -.->|"updates avatar UI"| node_profile
node_view_story_js -->|"posts user link"| node_flask
node_about_js -->|"reads form"| node_about

click node_flask "https://github.com/hekimaconstant/storyforge/blob/main/app.py"
click node_accounts "https://github.com/hekimaconstant/storyforge/blob/main/app.py"
click node_story_browse "https://github.com/hekimaconstant/storyforge/blob/main/app.py"
click node_story_publish "https://github.com/hekimaconstant/storyforge/blob/main/app.py"
click node_story_view "https://github.com/hekimaconstant/storyforge/blob/main/app.py"
click node_story_export "https://github.com/hekimaconstant/storyforge/blob/main/app.py"
click node_profile "https://github.com/hekimaconstant/storyforge/blob/main/app.py"
click node_about "https://github.com/hekimaconstant/storyforge/blob/main/templates/about_us.html"
click node_story_service "https://github.com/hekimaconstant/storyforge/blob/main/services/story_service.py"
click node_prompt_builder "https://github.com/hekimaconstant/storyforge/blob/main/services/prompt_builder.py"
click node_ai_service "https://github.com/hekimaconstant/storyforge/blob/main/services/hf_service.py"
click node_thumbnail "https://github.com/hekimaconstant/storyforge/blob/main/services/thumbnail_generator/thumbnail_generator.py"
click node_db_adapter "https://github.com/hekimaconstant/storyforge/blob/main/database/db.py"
click node_database "https://github.com/hekimaconstant/storyforge/blob/main/database/schema.sql"
click node_exporter "https://github.com/hekimaconstant/storyforge/blob/main/services/exporter/exporter.py"
click node_templates "https://github.com/hekimaconstant/storyforge/tree/main/templates"
click node_profile_js "https://github.com/hekimaconstant/storyforge/blob/main/static/js/profile.js"
click node_view_story_js "https://github.com/hekimaconstant/storyforge/blob/main/static/js/view_story.js"
click node_about_js "https://github.com/hekimaconstant/storyforge/blob/main/static/js/about_us.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_flask,node_accounts,node_story_browse,node_story_publish,node_story_view,node_story_export,node_profile,node_about,node_exporter toneBlue
class node_story_service,node_prompt_builder,node_ai_service,node_thumbnail toneAmber
class node_db_adapter,node_database toneMint
class node_templates,node_profile_js,node_view_story_js,node_about_js toneRose
class node_visitor toneIndigo
```

## Components

### Web application

- [Flask routes](https://github.com/hekimaconstant/storyforge/blob/main/app.py): `app.py`
- [Accounts](https://github.com/hekimaconstant/storyforge/blob/main/app.py): `app.py`
- [Story browsing](https://github.com/hekimaconstant/storyforge/blob/main/app.py): `app.py`
- [Story publishing](https://github.com/hekimaconstant/storyforge/blob/main/app.py): `app.py`
- [Story viewing](https://github.com/hekimaconstant/storyforge/blob/main/app.py): `app.py`
- [Story export](https://github.com/hekimaconstant/storyforge/blob/main/app.py): `app.py`
- [Profiles and avatars](https://github.com/hekimaconstant/storyforge/blob/main/app.py): `app.py`
- [About and contact](https://github.com/hekimaconstant/storyforge/blob/main/templates/about_us.html): `templates/about_us.html`
- [Document exporters](https://github.com/hekimaconstant/storyforge/blob/main/services/exporter/exporter.py): `services/exporter/exporter.py`

### Story generation

- [Story service](https://github.com/hekimaconstant/storyforge/blob/main/services/story_service.py): `services/story_service.py`
- [Prompt builder](https://github.com/hekimaconstant/storyforge/blob/main/services/prompt_builder.py): `services/prompt_builder.py`
- [AI generation](https://github.com/hekimaconstant/storyforge/blob/main/services/hf_service.py): `services/hf_service.py`
- [Thumbnail URLs](https://github.com/hekimaconstant/storyforge/blob/main/services/thumbnail_generator/thumbnail_generator.py): `services/thumbnail_generator/thumbnail_generator.py`

### Persistence

- [Database adapter](https://github.com/hekimaconstant/storyforge/blob/main/database/db.py): `database/db.py`
- [Story and user data](https://github.com/hekimaconstant/storyforge/blob/main/database/schema.sql): `database/schema.sql`

### Presentation

- [Page templates](https://github.com/hekimaconstant/storyforge/tree/main/templates): `templates`
- [Avatar interaction](https://github.com/hekimaconstant/storyforge/blob/main/static/js/profile.js): `static/js/profile.js`
- [Story-page interaction](https://github.com/hekimaconstant/storyforge/blob/main/static/js/view_story.js): `static/js/view_story.js`
- [Contact interaction](https://github.com/hekimaconstant/storyforge/blob/main/static/js/about_us.js): `static/js/about_us.js`

### Other components

- **Visitor**

## Connections

- Visitor → Flask routes: uses
- Flask routes → Accounts: routes (evidence: `app.py`)
- Flask routes → Story browsing: routes (evidence: `app.py`)
- Flask routes → Story publishing: routes (evidence: `app.py`)
- Flask routes → Story viewing: routes (evidence: `app.py`)
- Flask routes → Story export: routes (evidence: `app.py`)
- Flask routes → Profiles and avatars: routes (evidence: `app.py`)
- Flask routes → Database adapter: queries (evidence: `app.py`)
- Story publishing → Story service: generates (evidence: `app.py`)
- Story service → Prompt builder: builds prompt (evidence: `services/story_service.py`)
- Story service → AI generation: requests story (evidence: `services/story_service.py`)
- Flask routes → Thumbnail URLs: uses (evidence: `app.py`)
- Story export → Document exporters: formats files (evidence: `app.py`)
- Database adapter → Story and user data: reads and writes
- Flask routes → Page templates: renders pages
- Avatar interaction → Profiles and avatars: updates avatar UI
- Story-page interaction → Flask routes: posts user link (evidence: `static/js/view_story.js`)
- Contact interaction → About and contact: reads form (evidence: `static/js/about_us.js`)
