# redimp/otterwiki architecture

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

- Interactive diagram: https://gitdiagram.com/redimp/otterwiki
- Repository: https://github.com/redimp/otterwiki

## Overview

An Otter Wiki is a Flask-based collaborative Markdown wiki whose pages and attachments are versioned in Git. Users browse, edit, and manage pages through web views; the server routes requests into wiki, rendering, authentication, and storage logic, while the browser editor supplies Markdown-oriented editing and attachment upload. The README also documents page history, customizable sidebar/index, extended Markdown, and experimental Git HTTP access. Several of those subsystems are represented by their exact source paths but were not sampled, so their internal links are omitted rather than inferred.

Main entry points: [`otterwiki/views.py`](https://github.com/redimp/otterwiki/blob/main/otterwiki/views.py) (Web views), [`otterwiki/server.py`](https://github.com/redimp/otterwiki/blob/main/otterwiki/server.py) (Flask server), [`otterwiki/renderer.py`](https://github.com/redimp/otterwiki/blob/main/otterwiki/renderer.py) (Markdown renderer), [`otterwiki/wiki.py`](https://github.com/redimp/otterwiki/blob/main/otterwiki/wiki.py) (Page operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_server["Flask server<br/>[server.py]"]
  node_views["Web views<br/>[views.py]"]
end

subgraph group_content["Wiki content"]
  node_page["Page operations<br/>[wiki.py]"]
  node_gitstorage[("Git storage<br/>[gitstorage.py]")]
  node_renderer["Markdown renderer<br/>[renderer.py]"]
  node_pageindex["Page index<br/>[pageindex.py]"]
  node_sidebar["Sidebar<br/>[sidebar.py]"]
  node_backlinks["Backlinks<br/>[backlinks.py]"]
  node_sitemap["Sitemap<br/>[sitemap.py]"]
end

subgraph group_editor["Browser editor"]
  node_editor["CodeMirror editor<br/>[index.js]"]
  node_formatting["Markdown formatting"]
  node_editorstate["Editor state helpers<br/>[helpers.js]"]
  node_attachments["Inline attachments"]
end

subgraph group_extensions["Extensions and integrations"]
  node_plugins["Plugin system<br/>[plugins.py]"]
  node_embeddings["Markdown embeddings"]
  node_rendererplugins["Renderer plugins"]
  node_repomgmt["Repository management<br/>[repomgmt.py]"]
  node_gitremote["Git HTTP access<br/>[remote.py]"]
end

subgraph group_identity["Identity and settings"]
  node_auth["Authentication<br/>[auth.py]"]
  node_models[("Database models<br/>[models.py]")]
  node_preferences["Preferences<br/>[preferences.py]"]
end

node_reader(("Wiki user"))

node_reader -->|"uses wiki"| node_server
node_server -->|"registers routes"| node_views
node_views -->|"handles page requests"| node_page
node_views -->|"checks identity"| node_auth
node_auth -->|"queries users"| node_models
node_page -->|"reads and writes"| node_gitstorage
node_views -->|"renders pages"| node_renderer
node_renderer -->|"uses hooks"| node_plugins
node_renderer -->|"delegates rendering"| node_rendererplugins
node_renderer -.->|"renders embeddings"| node_embeddings
node_views -->|"builds page index"| node_pageindex
node_views -->|"renders sidebar"| node_sidebar
node_page -->|"uses backlinks"| node_backlinks
node_views -->|"serves sitemap"| node_sitemap
node_server -->|"sets up plugins"| node_plugins
node_views -->|"manages preferences"| node_preferences
node_reader -->|"edits Markdown"| node_editor
node_editor -->|"installs commands"| node_formatting
node_formatting -->|"updates document"| node_editorstate
node_editor -->|"enables uploads"| node_attachments
node_reader -.->|"clones or pushes"| node_gitremote
node_views -->|"manages repository"| node_repomgmt
node_server -->|"initializes storage"| node_gitstorage

click node_server "https://github.com/redimp/otterwiki/blob/main/otterwiki/server.py"
click node_views "https://github.com/redimp/otterwiki/blob/main/otterwiki/views.py"
click node_auth "https://github.com/redimp/otterwiki/blob/main/otterwiki/auth.py"
click node_models "https://github.com/redimp/otterwiki/blob/main/otterwiki/models.py"
click node_preferences "https://github.com/redimp/otterwiki/blob/main/otterwiki/preferences.py"
click node_page "https://github.com/redimp/otterwiki/blob/main/otterwiki/wiki.py"
click node_gitstorage "https://github.com/redimp/otterwiki/blob/main/otterwiki/gitstorage.py"
click node_renderer "https://github.com/redimp/otterwiki/blob/main/otterwiki/renderer.py"
click node_pageindex "https://github.com/redimp/otterwiki/blob/main/otterwiki/pageindex.py"
click node_sidebar "https://github.com/redimp/otterwiki/blob/main/otterwiki/sidebar.py"
click node_backlinks "https://github.com/redimp/otterwiki/blob/main/otterwiki/backlinks.py"
click node_sitemap "https://github.com/redimp/otterwiki/blob/main/otterwiki/sitemap.py"
click node_editor "https://github.com/redimp/otterwiki/blob/main/frontend/src/index.js"
click node_formatting "https://github.com/redimp/otterwiki/blob/main/frontend/src/editor-formatting.js"
click node_editorstate "https://github.com/redimp/otterwiki/blob/main/frontend/src/helpers.js"
click node_attachments "https://github.com/redimp/otterwiki/blob/main/frontend/src/inline-attachment.js"
click node_plugins "https://github.com/redimp/otterwiki/blob/main/otterwiki/plugins.py"
click node_embeddings "https://github.com/redimp/otterwiki/blob/main/otterwiki/renderer_embeddings.py"
click node_rendererplugins "https://github.com/redimp/otterwiki/blob/main/otterwiki/renderer_plugins.py"
click node_repomgmt "https://github.com/redimp/otterwiki/blob/main/otterwiki/repomgmt.py"
click node_gitremote "https://github.com/redimp/otterwiki/blob/main/otterwiki/remote.py"

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_server,node_views,node_reader toneBlue
class node_page,node_gitstorage,node_renderer,node_pageindex,node_sidebar,node_backlinks,node_sitemap toneAmber
class node_editor,node_formatting,node_editorstate,node_attachments toneMint
class node_plugins,node_embeddings,node_rendererplugins,node_repomgmt,node_gitremote toneRose
class node_auth,node_models,node_preferences toneIndigo
```

## Components

### Web application

- [Flask server](https://github.com/redimp/otterwiki/blob/main/otterwiki/server.py): `otterwiki/server.py`
- [Web views](https://github.com/redimp/otterwiki/blob/main/otterwiki/views.py): `otterwiki/views.py`

### Wiki content

- [Page operations](https://github.com/redimp/otterwiki/blob/main/otterwiki/wiki.py): `otterwiki/wiki.py`
- [Git storage](https://github.com/redimp/otterwiki/blob/main/otterwiki/gitstorage.py): `otterwiki/gitstorage.py`
- [Markdown renderer](https://github.com/redimp/otterwiki/blob/main/otterwiki/renderer.py): `otterwiki/renderer.py`
- [Page index](https://github.com/redimp/otterwiki/blob/main/otterwiki/pageindex.py): `otterwiki/pageindex.py`
- [Sidebar](https://github.com/redimp/otterwiki/blob/main/otterwiki/sidebar.py): `otterwiki/sidebar.py`
- [Backlinks](https://github.com/redimp/otterwiki/blob/main/otterwiki/backlinks.py): `otterwiki/backlinks.py`
- [Sitemap](https://github.com/redimp/otterwiki/blob/main/otterwiki/sitemap.py): `otterwiki/sitemap.py`

### Browser editor

- [CodeMirror editor](https://github.com/redimp/otterwiki/blob/main/frontend/src/index.js): `frontend/src/index.js`
- [Markdown formatting](https://github.com/redimp/otterwiki/blob/main/frontend/src/editor-formatting.js): `frontend/src/editor-formatting.js`
- [Editor state helpers](https://github.com/redimp/otterwiki/blob/main/frontend/src/helpers.js): `frontend/src/helpers.js`
- [Inline attachments](https://github.com/redimp/otterwiki/blob/main/frontend/src/inline-attachment.js): `frontend/src/inline-attachment.js`

### Extensions and integrations

- [Plugin system](https://github.com/redimp/otterwiki/blob/main/otterwiki/plugins.py): `otterwiki/plugins.py`
- [Markdown embeddings](https://github.com/redimp/otterwiki/blob/main/otterwiki/renderer_embeddings.py): `otterwiki/renderer_embeddings.py`
- [Renderer plugins](https://github.com/redimp/otterwiki/blob/main/otterwiki/renderer_plugins.py): `otterwiki/renderer_plugins.py`
- [Repository management](https://github.com/redimp/otterwiki/blob/main/otterwiki/repomgmt.py): `otterwiki/repomgmt.py`
- [Git HTTP access](https://github.com/redimp/otterwiki/blob/main/otterwiki/remote.py): `otterwiki/remote.py`

### Identity and settings

- [Authentication](https://github.com/redimp/otterwiki/blob/main/otterwiki/auth.py): `otterwiki/auth.py`
- [Database models](https://github.com/redimp/otterwiki/blob/main/otterwiki/models.py): `otterwiki/models.py`
- [Preferences](https://github.com/redimp/otterwiki/blob/main/otterwiki/preferences.py): `otterwiki/preferences.py`

### Other components

- **Wiki user**

## Connections

- Wiki user → Flask server: uses wiki
- Flask server → Web views: registers routes (evidence: `otterwiki/server.py`)
- Web views → Page operations: handles page requests (evidence: `otterwiki/views.py`)
- Web views → Authentication: checks identity (evidence: `otterwiki/views.py`)
- Authentication → Database models: queries users (evidence: `otterwiki/auth.py`)
- Page operations → Git storage: reads and writes (evidence: `otterwiki/wiki.py`)
- Web views → Markdown renderer: renders pages (evidence: `otterwiki/views.py`)
- Markdown renderer → Plugin system: uses hooks (evidence: `otterwiki/renderer.py`)
- Markdown renderer → Renderer plugins: delegates rendering (evidence: `otterwiki/renderer.py`)
- Markdown renderer → Markdown embeddings: renders embeddings (evidence: `otterwiki/renderer_embeddings.py`)
- Web views → Page index: builds page index (evidence: `otterwiki/views.py`)
- Web views → Sidebar: renders sidebar (evidence: `otterwiki/views.py`)
- Page operations → Backlinks: uses backlinks (evidence: `otterwiki/wiki.py`)
- Web views → Sitemap: serves sitemap (evidence: `otterwiki/views.py`)
- Flask server → Plugin system: sets up plugins (evidence: `otterwiki/server.py`)
- Web views → Preferences: manages preferences (evidence: `otterwiki/views.py`)
- Wiki user → CodeMirror editor: edits Markdown
- CodeMirror editor → Markdown formatting: installs commands (evidence: `frontend/src/index.js`)
- Markdown formatting → Editor state helpers: updates document (evidence: `frontend/src/editor-formatting.js`)
- CodeMirror editor → Inline attachments: enables uploads (evidence: `frontend/src/index.js`)
- Wiki user → Git HTTP access: clones or pushes
- Web views → Repository management: manages repository (evidence: `otterwiki/views.py`)
- Flask server → Git storage: initializes storage (evidence: `otterwiki/server.py`)
