# mickael-kerjean/filestash architecture

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

- Interactive diagram: https://gitdiagram.com/mickael-kerjean/filestash
- Repository: https://github.com/mickael-kerjean/filestash

## Overview

Filestash is a plugin-driven file management platform: users authenticate, browse or modify files across storage backends, and can search, share, preview, or automate file activity. The server initializes plugins and workflows, then exposes HTTP routes for the web client and APIs; optional plugins add storage, authentication, editors, and protocol gateways such as MCP. The README also describes native synchronization and gateway products, but this repository’s sampled runtime is principally the server. Several subsystem links below are documented capabilities rather than inspected calls because their implementation excerpts were not provided.

Main entry points: [`server/routes.go`](https://github.com/mickael-kerjean/filestash/blob/master/server/routes.go) (HTTP Routes), [`server/plugin/index.go`](https://github.com/mickael-kerjean/filestash/blob/master/server/plugin/index.go) (Plugin Registry), [`server/pkg/files`](https://github.com/mickael-kerjean/filestash/tree/master/server/pkg/files) (File Operations), [`cmd/main.go`](https://github.com/mickael-kerjean/filestash/blob/master/cmd/main.go) (Server Startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server Runtime"]
  node_main["Server Startup<br/>[main.go]"]
  node_routes["HTTP Routes<br/>[routes.go]"]
  node_kernel["App Kernel"]
  node_middleware["Request Middleware<br/>[index.go]"]
  node_admin["Admin Console<br/>[handler.go]"]
  node_frontend["Web Frontend<br/>[static.go]"]
end

subgraph group_access["Identity And Access"]
  node_session["Session Authentication"]
  node_idp["Identity Provider Login"]
  node_token["Token Service<br/>[handler.go]"]
end

subgraph group_files["File Management"]
  node_files["File Operations"]
  node_save["File Save<br/>[handler_save.go]"]
  node_search["File Search<br/>[handler_search.go]"]
end

subgraph group_extensions["Plugin Ecosystem"]
  node_searchplugin["SQLite Full-Text Search<br/>[query.go]"]
  node_storage["Storage Backends<br/>[index.go]"]
  node_plugins["Plugin Registry<br/>[index.go]"]
  node_extension["Extension Runtime<br/>[runtime.go]"]
  node_editors["File Editors<br/>[handler.go]"]
  node_mcp["MCP Gateway<br/>[handler.go]"]
end

subgraph group_automation["Sharing And Automation"]
  node_shares["Shared Links<br/>[handler.go]"]
  node_workflow["Workflow Engine<br/>[handler.go]"]
  node_triggers["Workflow Triggers"]
  node_journal[("Event Journal")]
end

node_user(("Web User"))
node_externalstorage[("External Storage")]
node_mcpclient(("MCP Client"))

node_main -->|"discovers"| node_plugins
node_main -->|"initializes"| node_workflow
node_main -->|"builds routes"| node_routes
node_user -.->|"uses web/API"| node_routes
node_routes -->|"routes authentication"| node_session
node_routes -->|"routes token requests"| node_token
node_routes -->|"routes file requests"| node_files
node_routes -->|"routes admin requests"| node_admin
node_routes -->|"routes sharing"| node_shares
node_routes -->|"routes workflows"| node_workflow
node_routes -->|"wraps handlers"| node_middleware
node_session -->|"injects token"| node_token
node_idp -->|"injects token"| node_token
node_files -.->|"dispatches save"| node_save
node_files -->|"dispatches search"| node_search
node_search -->|"queries hook"| node_searchplugin
node_save -->|"publishes events"| node_journal
node_plugins -->|"registers backends"| node_storage
node_main -->|"initializes extensions"| node_extension
node_files -.->|"accesses storage"| node_storage
node_plugins -->|"registers editor"| node_editors
node_plugins -->|"registers gateway"| node_mcp
node_plugins -.->|"registers search"| node_searchplugin
node_mcpclient -.->|"connects gateway"| node_mcp
node_editors -->|"fetches editor discovery"| node_externalstorage
node_workflow -.->|"accepts triggers"| node_triggers
node_triggers -.->|"starts workflows"| node_workflow
node_shares -.->|"shares file paths"| node_files

click node_main "https://github.com/mickael-kerjean/filestash/blob/master/cmd/main.go"
click node_routes "https://github.com/mickael-kerjean/filestash/blob/master/server/routes.go"
click node_kernel "https://github.com/mickael-kerjean/filestash/tree/master/server/pkg/kernel"
click node_middleware "https://github.com/mickael-kerjean/filestash/blob/master/server/middleware/index.go"
click node_session "https://github.com/mickael-kerjean/filestash/blob/master/server/pkg/session/handler_auth_direct.go"
click node_idp "https://github.com/mickael-kerjean/filestash/blob/master/server/pkg/session/handler_auth_idp.go"
click node_token "https://github.com/mickael-kerjean/filestash/blob/master/server/pkg/token/handler.go"
click node_files "https://github.com/mickael-kerjean/filestash/tree/master/server/pkg/files"
click node_save "https://github.com/mickael-kerjean/filestash/blob/master/server/pkg/files/handler_save.go"
click node_search "https://github.com/mickael-kerjean/filestash/blob/master/server/pkg/files/handler_search.go"
click node_searchplugin "https://github.com/mickael-kerjean/filestash/blob/master/server/plugin/plg_search_sqlitefts/query.go"
click node_storage "https://github.com/mickael-kerjean/filestash/blob/master/server/plugin/plg_backend_local/index.go"
click node_plugins "https://github.com/mickael-kerjean/filestash/blob/master/server/plugin/index.go"
click node_extension "https://github.com/mickael-kerjean/filestash/blob/master/server/pkg/extension/adapter/runtime/runtime.go"
click node_editors "https://github.com/mickael-kerjean/filestash/blob/master/server/plugin/plg_editor_wopi/handler.go"
click node_mcp "https://github.com/mickael-kerjean/filestash/blob/master/server/plugin/plg_handler_mcp/handler.go"
click node_admin "https://github.com/mickael-kerjean/filestash/blob/master/server/pkg/admin/handler.go"
click node_frontend "https://github.com/mickael-kerjean/filestash/blob/master/server/pkg/frontend/static.go"
click node_shares "https://github.com/mickael-kerjean/filestash/blob/master/server/pkg/share/handler.go"
click node_workflow "https://github.com/mickael-kerjean/filestash/blob/master/server/pkg/workflow/handler.go"
click node_triggers "https://github.com/mickael-kerjean/filestash/tree/master/server/pkg/workflow/trigger"
click node_journal "https://github.com/mickael-kerjean/filestash/tree/master/server/pkg/journal"

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_main,node_routes,node_kernel,node_middleware,node_admin,node_frontend,node_user,node_mcpclient toneBlue
class node_session,node_idp,node_token,node_externalstorage toneAmber
class node_files,node_save,node_search toneMint
class node_searchplugin,node_storage,node_plugins,node_extension,node_editors,node_mcp toneRose
class node_shares,node_workflow,node_triggers,node_journal toneIndigo
```

## Components

### Server Runtime

- [Server Startup](https://github.com/mickael-kerjean/filestash/blob/master/cmd/main.go): `cmd/main.go`
- [HTTP Routes](https://github.com/mickael-kerjean/filestash/blob/master/server/routes.go): `server/routes.go`
- [App Kernel](https://github.com/mickael-kerjean/filestash/tree/master/server/pkg/kernel): `server/pkg/kernel`
- [Request Middleware](https://github.com/mickael-kerjean/filestash/blob/master/server/middleware/index.go): `server/middleware/index.go`
- [Admin Console](https://github.com/mickael-kerjean/filestash/blob/master/server/pkg/admin/handler.go): `server/pkg/admin/handler.go`
- [Web Frontend](https://github.com/mickael-kerjean/filestash/blob/master/server/pkg/frontend/static.go): `server/pkg/frontend/static.go`

### Identity And Access

- [Session Authentication](https://github.com/mickael-kerjean/filestash/blob/master/server/pkg/session/handler_auth_direct.go): `server/pkg/session/handler_auth_direct.go`
- [Identity Provider Login](https://github.com/mickael-kerjean/filestash/blob/master/server/pkg/session/handler_auth_idp.go): `server/pkg/session/handler_auth_idp.go`
- [Token Service](https://github.com/mickael-kerjean/filestash/blob/master/server/pkg/token/handler.go): `server/pkg/token/handler.go`

### File Management

- [File Operations](https://github.com/mickael-kerjean/filestash/tree/master/server/pkg/files): `server/pkg/files`
- [File Save](https://github.com/mickael-kerjean/filestash/blob/master/server/pkg/files/handler_save.go): `server/pkg/files/handler_save.go`
- [File Search](https://github.com/mickael-kerjean/filestash/blob/master/server/pkg/files/handler_search.go): `server/pkg/files/handler_search.go`

### Plugin Ecosystem

- [SQLite Full-Text Search](https://github.com/mickael-kerjean/filestash/blob/master/server/plugin/plg_search_sqlitefts/query.go): `server/plugin/plg_search_sqlitefts/query.go`
- [Storage Backends](https://github.com/mickael-kerjean/filestash/blob/master/server/plugin/plg_backend_local/index.go): `server/plugin/plg_backend_local/index.go`
- [Plugin Registry](https://github.com/mickael-kerjean/filestash/blob/master/server/plugin/index.go): `server/plugin/index.go`
- [Extension Runtime](https://github.com/mickael-kerjean/filestash/blob/master/server/pkg/extension/adapter/runtime/runtime.go): `server/pkg/extension/adapter/runtime/runtime.go`
- [File Editors](https://github.com/mickael-kerjean/filestash/blob/master/server/plugin/plg_editor_wopi/handler.go): `server/plugin/plg_editor_wopi/handler.go`
- [MCP Gateway](https://github.com/mickael-kerjean/filestash/blob/master/server/plugin/plg_handler_mcp/handler.go): `server/plugin/plg_handler_mcp/handler.go`

### Sharing And Automation

- [Shared Links](https://github.com/mickael-kerjean/filestash/blob/master/server/pkg/share/handler.go): `server/pkg/share/handler.go`
- [Workflow Engine](https://github.com/mickael-kerjean/filestash/blob/master/server/pkg/workflow/handler.go): `server/pkg/workflow/handler.go`
- [Workflow Triggers](https://github.com/mickael-kerjean/filestash/tree/master/server/pkg/workflow/trigger): `server/pkg/workflow/trigger`
- [Event Journal](https://github.com/mickael-kerjean/filestash/tree/master/server/pkg/journal): `server/pkg/journal`

### Other components

- **Web User**
- **External Storage**
- **MCP Client**

## Connections

- Server Startup → Plugin Registry: discovers (evidence: `cmd/main.go`)
- Server Startup → Workflow Engine: initializes (evidence: `cmd/main.go`)
- Server Startup → HTTP Routes: builds routes (evidence: `cmd/main.go`)
- Web User → HTTP Routes: uses web/API
- HTTP Routes → Session Authentication: routes authentication (evidence: `server/routes.go`)
- HTTP Routes → Token Service: routes token requests (evidence: `server/routes.go`)
- HTTP Routes → File Operations: routes file requests (evidence: `server/routes.go`)
- HTTP Routes → Admin Console: routes admin requests (evidence: `server/routes.go`)
- HTTP Routes → Shared Links: routes sharing (evidence: `server/routes.go`)
- HTTP Routes → Workflow Engine: routes workflows (evidence: `server/routes.go`)
- HTTP Routes → Request Middleware: wraps handlers (evidence: `server/routes.go`)
- Session Authentication → Token Service: injects token (evidence: `server/pkg/session/handler_auth_direct.go`)
- Identity Provider Login → Token Service: injects token (evidence: `server/pkg/session/handler_auth_idp.go`)
- File Operations → File Save: dispatches save
- File Operations → File Search: dispatches search
- File Search → SQLite Full-Text Search: queries hook (evidence: `server/pkg/files/handler_search.go`)
- File Save → Event Journal: publishes events (evidence: `server/pkg/files/handler_save.go`)
- Plugin Registry → Storage Backends: registers backends (evidence: `server/plugin/index.go`)
- Server Startup → Extension Runtime: initializes extensions (evidence: `cmd/main.go`)
- File Operations → Storage Backends: accesses storage
- Plugin Registry → File Editors: registers editor (evidence: `server/plugin/index.go`)
- Plugin Registry → MCP Gateway: registers gateway (evidence: `server/plugin/index.go`)
- Plugin Registry → SQLite Full-Text Search: registers search
- MCP Client → MCP Gateway: connects gateway
- File Editors → External Storage: fetches editor discovery (evidence: `server/plugin/plg_editor_wopi/handler.go`)
- Workflow Engine → Workflow Triggers: accepts triggers
- Workflow Triggers → Workflow Engine: starts workflows
- Shared Links → File Operations: shares file paths
