# victor3spoir/mdvault architecture

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

- Interactive diagram: https://gitdiagram.com/victor3spoir/mdvault
- Repository: https://github.com/victor3spoir/mdvault

## Overview

MDVault is a GitHub-backed Markdown CMS: a writer manages articles, short-form posts, custom Vault content, and media through the CMS; saves and publishing become repository commits, leaving portable Markdown and assets for downstream site consumers. The map includes the documented dashboard, settings, filtering, rich editing, translation, and private-media capabilities. The README and tree support the product boundaries and persistence flow; sampled source confirms the CMS shell, router, GitHub client, and repository-path validation, but not detailed handler-to-server wiring, so those links are kept at subsystem level.

Main entry points: [`mdvault/src/routes/cms/route.tsx`](https://github.com/victor3spoir/mdvault/blob/main/mdvault/src/routes/cms/route.tsx) (CMS shell), [`mdvault/src/features/content/content-store.server.ts`](https://github.com/victor3spoir/mdvault/blob/main/mdvault/src/features/content/content-store.server.ts) (Shared content store), [`mdvault/src/features/articles`](https://github.com/victor3spoir/mdvault/tree/main/mdvault/src/features/articles) (Articles), [`mdvault/src/features/media`](https://github.com/victor3spoir/mdvault/tree/main/mdvault/src/features/media) (Media library)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace"]
  node_cms["CMS shell<br/>[route.tsx]"]
  node_dashboard["Dashboard"]
  node_palette["Command palette"]
  node_settings["Settings"]
end

subgraph group_writing["Content authoring"]
  node_articles["Articles"]
  node_article_editor["Rich editor"]
  node_posts["Plain-text posts"]
  node_vault["Custom Vault types"]
  node_content_render["Content rendering"]
end

subgraph group_assets["Media and assets"]
  node_media_library["Media library"]
  node_media_api["Media proxy<br/>[media.tsx]"]
  node_private_media["Private media delivery"]
end

subgraph group_services["Content services"]
  node_content_store["Shared content store"]
  node_github_files["GitHub file access"]
  node_github_client["GitHub client"]
  node_repo_paths["Path validation<br/>[repository-path.ts]"]
end

subgraph group_persistence["Git persistence"]
  node_repository[("Content repository")]
end

node_writer(("Content writer"))
node_github{{"GitHub API"}}
node_site_consumer(("Static site or app"))

node_writer -->|"uses"| node_cms
node_cms -->|"routes to"| node_dashboard
node_cms -->|"routes to"| node_articles
node_cms -->|"routes to"| node_posts
node_cms -->|"routes to"| node_vault
node_cms -->|"routes to"| node_media_library
node_cms -->|"routes to"| node_settings
node_cms -->|"mounts"| node_palette
node_articles -->|"edits with"| node_article_editor
node_articles -->|"previews with"| node_content_render
node_posts -->|"renders with"| node_content_render
node_vault -->|"renders with"| node_content_render
node_articles -->|"reads and writes"| node_content_store
node_posts -->|"reads and writes"| node_content_store
node_vault -->|"reads and writes"| node_content_store
node_dashboard -->|"reads activity"| node_content_store
node_media_library -->|"checks references"| node_content_store
node_media_library -->|"requests private media"| node_media_api
node_media_api -->|"serves through"| node_private_media
node_content_store -->|"reads and commits"| node_github_files
node_media_library -->|"manages assets"| node_github_files
node_github_files -->|"uses"| node_github_client
node_github_client -->|"calls"| node_github
node_github -->|"reads and commits"| node_repository
node_github_files -->|"validates paths"| node_repo_paths
node_site_consumer -->|"reads Markdown and media"| node_repository

click node_cms "https://github.com/victor3spoir/mdvault/blob/main/mdvault/src/routes/cms/route.tsx"
click node_dashboard "https://github.com/victor3spoir/mdvault/tree/main/mdvault/src/features/dashboard"
click node_palette "https://github.com/victor3spoir/mdvault/blob/main/mdvault/src/components/command-palette.tsx"
click node_settings "https://github.com/victor3spoir/mdvault/tree/main/mdvault/src/features/settings"
click node_articles "https://github.com/victor3spoir/mdvault/tree/main/mdvault/src/features/articles"
click node_article_editor "https://github.com/victor3spoir/mdvault/blob/main/mdvault/src/features/articles/components/editor/rich-text-editor.tsx"
click node_posts "https://github.com/victor3spoir/mdvault/tree/main/mdvault/src/features/posts"
click node_vault "https://github.com/victor3spoir/mdvault/tree/main/mdvault/src/features/vault"
click node_content_render "https://github.com/victor3spoir/mdvault/blob/main/mdvault/src/features/content/components/markdown-content.tsx"
click node_media_library "https://github.com/victor3spoir/mdvault/tree/main/mdvault/src/features/media"
click node_media_api "https://github.com/victor3spoir/mdvault/blob/main/mdvault/src/routes/api/media.tsx"
click node_private_media "https://github.com/victor3spoir/mdvault/blob/main/mdvault/src/lib/server/media-cache.server.ts"
click node_content_store "https://github.com/victor3spoir/mdvault/blob/main/mdvault/src/features/content/content-store.server.ts"
click node_github_files "https://github.com/victor3spoir/mdvault/blob/main/mdvault/src/lib/server/github-files.server.ts"
click node_github_client "https://github.com/victor3spoir/mdvault/blob/main/mdvault/src/integrations/github/github-client.server.ts"
click node_repo_paths "https://github.com/victor3spoir/mdvault/blob/main/mdvault/src/lib/repository-path.ts"

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_cms,node_dashboard,node_palette,node_settings toneBlue
class node_articles,node_article_editor,node_posts,node_vault,node_content_render toneAmber
class node_media_library,node_media_api,node_private_media,node_github toneMint
class node_content_store,node_github_files,node_github_client,node_repo_paths toneRose
class node_repository,node_writer,node_site_consumer toneIndigo
```

## Components

### Workspace

- [CMS shell](https://github.com/victor3spoir/mdvault/blob/main/mdvault/src/routes/cms/route.tsx): `mdvault/src/routes/cms/route.tsx`
- [Dashboard](https://github.com/victor3spoir/mdvault/tree/main/mdvault/src/features/dashboard): `mdvault/src/features/dashboard`
- [Command palette](https://github.com/victor3spoir/mdvault/blob/main/mdvault/src/components/command-palette.tsx): `mdvault/src/components/command-palette.tsx`
- [Settings](https://github.com/victor3spoir/mdvault/tree/main/mdvault/src/features/settings): `mdvault/src/features/settings`

### Content authoring

- [Articles](https://github.com/victor3spoir/mdvault/tree/main/mdvault/src/features/articles): `mdvault/src/features/articles`
- [Rich editor](https://github.com/victor3spoir/mdvault/blob/main/mdvault/src/features/articles/components/editor/rich-text-editor.tsx): `mdvault/src/features/articles/components/editor/rich-text-editor.tsx`
- [Plain-text posts](https://github.com/victor3spoir/mdvault/tree/main/mdvault/src/features/posts): `mdvault/src/features/posts`
- [Custom Vault types](https://github.com/victor3spoir/mdvault/tree/main/mdvault/src/features/vault): `mdvault/src/features/vault`
- [Content rendering](https://github.com/victor3spoir/mdvault/blob/main/mdvault/src/features/content/components/markdown-content.tsx): `mdvault/src/features/content/components/markdown-content.tsx`

### Media and assets

- [Media library](https://github.com/victor3spoir/mdvault/tree/main/mdvault/src/features/media): `mdvault/src/features/media`
- [Media proxy](https://github.com/victor3spoir/mdvault/blob/main/mdvault/src/routes/api/media.tsx): `mdvault/src/routes/api/media.tsx`
- [Private media delivery](https://github.com/victor3spoir/mdvault/blob/main/mdvault/src/lib/server/media-cache.server.ts): `mdvault/src/lib/server/media-cache.server.ts`

### Content services

- [Shared content store](https://github.com/victor3spoir/mdvault/blob/main/mdvault/src/features/content/content-store.server.ts): `mdvault/src/features/content/content-store.server.ts`
- [GitHub file access](https://github.com/victor3spoir/mdvault/blob/main/mdvault/src/lib/server/github-files.server.ts): `mdvault/src/lib/server/github-files.server.ts`
- [GitHub client](https://github.com/victor3spoir/mdvault/blob/main/mdvault/src/integrations/github/github-client.server.ts): `mdvault/src/integrations/github/github-client.server.ts`
- [Path validation](https://github.com/victor3spoir/mdvault/blob/main/mdvault/src/lib/repository-path.ts): `mdvault/src/lib/repository-path.ts`

### Git persistence

- **Content repository**

### Other components

- **Content writer**
- **GitHub API**
- **Static site or app**

## Connections

- Content writer → CMS shell: uses
- CMS shell → Dashboard: routes to
- CMS shell → Articles: routes to
- CMS shell → Plain-text posts: routes to
- CMS shell → Custom Vault types: routes to
- CMS shell → Media library: routes to
- CMS shell → Settings: routes to
- CMS shell → Command palette: mounts
- Articles → Rich editor: edits with
- Articles → Content rendering: previews with
- Plain-text posts → Content rendering: renders with
- Custom Vault types → Content rendering: renders with
- Articles → Shared content store: reads and writes
- Plain-text posts → Shared content store: reads and writes
- Custom Vault types → Shared content store: reads and writes
- Dashboard → Shared content store: reads activity
- Media library → Shared content store: checks references
- Media library → Media proxy: requests private media
- Media proxy → Private media delivery: serves through
- Shared content store → GitHub file access: reads and commits
- Media library → GitHub file access: manages assets
- GitHub file access → GitHub client: uses
- GitHub client → GitHub API: calls
- GitHub API → Content repository: reads and commits
- GitHub file access → Path validation: validates paths
- Static site or app → Content repository: reads Markdown and media