How aixploits/ignis works
1. Top-level shape
- Ignis is a monorepo split into a browser-facing client layer and a self-hosted server layer.
- The main product is the apps/ignis-server application, with shared packages under packages/ for the shim, bridge plugin, UI components, and core server utilities.
2. Primary runtime boundary
- The browser runs Obsidian UI code, but not native Electron.
- Ignis inserts a compatibility shim that emulates the Electron/Node APIs Obsidian expects, while the server keeps the vault files on disk and mediates access to them.
3. Server application
- apps/ignis-server/server/ is the central backend runtime.
- It exposes HTTP routes, manages vault access, serves static assets, handles settings, proxies cross-origin requests when needed, and hosts server-side plugins.
- The Dockerized server downloads Obsidian from its official source at first run; Obsidian itself is not vendored in the repo.
4. Browser-side bridge into Obsidian
- packages/bridge/ is the client-side Obsidian plugin that wires Ignis features into the app.
- It adds Ignis-specific settings tabs, status-bar indicators, workspace controls, plugin-related UI, and file actions such as upload/download.
- This package is the “integration surface” between the shimmed runtime and the user-visible Obsidian UI.
5. Compatibility shim layer
- packages/shim/ is the core emulation layer.
- It provides browser-compatible replacements for Electron APIs, Node modules, filesystem primitives, workspace handling, request/proxy behavior, WebSocket client behavior, and other globals Obsidian or community plugins expect.
- This package is what allows Obsidian’s renderer code to execute in a normal browser instead of Electron.
6. Shared server primitives
- packages/server-core/ contains lower-level infrastructure used by the server runtime.
- It includes filesystem/path helpers, WebSocket plumbing, error types, file-watcher logic, and write coalescing to reduce churn on slow or networked storage.
- This is the “core infra” boundary beneath route handlers and higher-level vault/plugin services.
7. Vault/service boundary
- packages/services/ and server routes together form the vault-access layer.
- The vault service abstraction is where file reads/writes, metadata, watching, and synchronization concerns are concentrated before they are exposed to the browser.
- In the architecture diagram, this sits between HTTP/WebSocket endpoints and the actual mounted vault filesystem.
8. HTTP/API surface
- apps/ignis-server/server/routes/ defines the external server API.
- Key route groups include bootstrap, filesystem operations, vault management, settings, plugin management, proxying, and version reporting.
- bootstrap is especially important: the README notes a pre-compressed bootstrap response that bundles vault info, vault list, metadata tree, and plugin list into one startup call.
9. Real-time collaboration and tab sync
- Ignis uses WebSockets for live synchronization between browser tabs on the same vault.
- The server publishes file/state changes; browser tabs subscribe and update within seconds.
- Shared utilities in server-core support the watcher and WS transport needed for this cross-tab synchronization loop.
10. Server-side plugin system
- Ignis has its own server plugin system separate from Obsidian’s community plugins.
- The plugin system code under apps/ignis-server/server/plugin-system/ handles discovery, config storage, lifecycle management, and Obsidian-facing plugin packaging.
- This is a distinct extension boundary from client-side community plugins: it extends the server itself, not just the browser runtime.
11. Headless sync as a server plugin
- apps/ignis-server/server/plugins/headless-sync/ is the main example of the server plugin model.
- It provides continuous sync without a browser tab, with auth, broadcasting, route handling, and an Obsidian-side companion plugin under obsidian/.
- The README notes it is mutually exclusive with Obsidian Sync per vault, making sync mode a vault-level server policy.
12. UI package
- packages/ui/ contains reusable Svelte-based UI components and views.
- These are used for vault management, sync setup, dialogs, and common controls that support the Ignis-specific UX inside Obsidian.
- In the diagram, this is the presentation layer consumed by the bridge plugin.
13. Deployment and edge boundaries
- The repo includes Docker and compose assets, plus examples for reverse-proxy setups such as Caddy and Authelia/basic-auth.
- HTTPS or localhost is materially important because browser crypto and clipboard APIs are required for full functionality; plain HTTP on non-localhost origins degrades features like graph view, outline, and sync.
- External access to some resources may be proxied through Ignis, or fetched directly for allowlisted CORS-friendly hosts.
14. Operational/performance concerns
- The architecture is optimized for large vaults and slow storage using cache-backed content access, indexer prefetch, and optional write coalescing.
- There is an LRU content cache, bounded memory behavior, and filesystem-watch driven refresh rather than loading the whole vault into memory.
- These concerns sit mainly in the server-core/shim/filesystem path, not in the UI.
15. What to show in a diagram
- Draw three major zones: browser tab running Obsidian + shim + bridge/UI, the Ignis server runtime, and the mounted vault filesystem.
- Add side paths for WebSocket sync, HTTP bootstrap/API calls, proxy requests, and the optional server-plugin subsystem.
- Show the headless-sync plugin as a server-side extension that can operate without an active browser tab.
Main entry points: server/index.js Server app · bootstrap.js HTTP routes · main.js Bridge plugin · headless-sync/index.js Headless sync
Components 17
Browser layer
Obsidian UI running in a normal browser with the compatibility shim and bridge plugin.
- Obsidian UI · Renderer-side Obsidian application code executed outside Electron.
- Shim · Browser-facing emulation of Electron, Node, filesystem, workspace, request, and WebSocket APIs.
packages/shim/src/init.js - Bridge plugin · Client-side integration surface that adds Ignis settings, status, workspace, and file actions.
packages/bridge/src/main.js - Sync companion · Obsidian-side companion UI and API layer for the headless sync server plugin.
apps/ignis-server/server/plugins/headless-sync/obsidian/src/main.js
Server layer
Ignis backend runtime, HTTP/API surface, vault mediation, and server-side plugins.
- Server app · Main Ignis server process that wires routes, services, assets, and plugin runtime together.
apps/ignis-server/server/index.js - HTTP routes · Bootstrap, filesystem, vault, settings, plugin, proxy, and version endpoints.
apps/ignis-server/server/routes/bootstrap.js - Proxy layer · Cross-origin request proxying and request URL handling for allowed external resources.
apps/ignis-server/server/routes/proxy.js - Settings store · Server-side settings handling and persistence for vault and runtime configuration.
apps/ignis-server/server/settings.js - Plugin system · Discovery, config storage, lifecycle management, and packaging for Ignis server plugins.
apps/ignis-server/server/plugin-system/manager.js - Headless sync · Server-side sync plugin that can run without an active browser tab and broadcasts vault changes.
apps/ignis-server/server/plugins/headless-sync/index.js - Static assets · Server-served HTML and CSS entry assets for the browser client shell.
apps/ignis-server/server/assets/index.html
Shared packages
Cross-cutting packages reused by the browser bridge, shim, and server runtime.
- UI kit · Reusable Svelte components and views for vault management, sync setup, dialogs, and common controls.
packages/ui/src/index.js - Vault service · Vault access boundary for reads, writes, metadata, watching, and synchronization concerns.
packages/services/src/vault-service.js - Server core · Low-level filesystem, path, WebSocket, error, watcher, and write-coalescing primitives.
packages/server-core/src/index.js - WebSocket sync · Server/browser live-change channel used for cross-tab synchronization.
packages/server-core/src/ws.js
Deployment
Container, compose, and proxy entrypoints for running Ignis.
- Docker runtime · Container and compose assets used to run Ignis and provision Obsidian on first start.
apps/ignis-server/Dockerfile - Vault files · On-disk vault storage mounted into the server and mediated through the vault service.
Connections 22
- Obsidian UI → Shim: calls APIs · Obsidian renderer code relies on Electron/Node/browser shims to run in a normal browser.
- Shim → Server app: requests data · The shim forwards filesystem, request, and runtime operations to the server.
- Bridge plugin → Obsidian UI: extends UI · The bridge injects Ignis-specific settings, status, workspace, and file actions into Obsidian.
- Bridge plugin → UI kit: renders controls · The bridge reuses shared UI components and views for Ignis-specific interactions.
- Server app → HTTP routes: hosts · The server entrypoint mounts the external HTTP/API surface.
- Server app → Settings store: loads config · Runtime startup and request handling depend on persisted server settings.
- Server app → Plugin system: loads plugins · The backend initializes and manages server-side extensions.
- HTTP routes → Vault service: reads/writes · API handlers delegate vault operations to the vault service boundary.
- Vault service → Server core: uses infra · Vault access builds on filesystem, watcher, WebSocket, and write-coalescing primitives.
- Vault service → Vault files: mediates · The service is the controlled path to the mounted vault on disk.
- Server core → WebSocket sync: implements · Shared infrastructure provides the WebSocket transport used for live updates.
- WebSocket sync → Shim: syncs state · Browser tabs subscribe to server-published changes through the WebSocket channel.
- HTTP routes → Proxy layer: proxies requests · HTTP endpoints can forward selected cross-origin traffic through Ignis.
- Plugin system → Headless sync: manages · The plugin system discovers and runs the headless sync extension.
- Headless sync → HTTP routes: adds routes · The headless sync plugin contributes its own API and auth endpoints.
- Headless sync → WebSocket sync: broadcasts · Headless sync publishes vault state changes over the realtime channel.
- Headless sync → Sync companion: companion UI · The server plugin ships with an Obsidian-side companion plugin for user interaction.
- Server app → Static assets: serves shell · The server delivers the browser entry assets and overrides.
- Docker runtime → Server app: starts · Container entrypoints launch the server runtime and provision dependencies.
- Docker runtime → Vault files: mounts · Deployment binds the vault directory into the server container.
- Bridge plugin → HTTP routes: bootstrap calls · The browser-side integration fetches startup data and settings via the HTTP API.
- Bridge plugin → WebSocket sync: subscribes · The bridge listens for live server events to keep tabs and UI state in sync.