+ Project Documentation
Roject
@@ -22,10 +27,14 @@What it is
- Roject is a self-hosted, browser-based CMS for creating, editing, and storing - HTML documents with assets, organised into projects. It is designed for individual - developers or small teams who want a lightweight authoring environment with no - external database dependency. + Roject is a self-hosted, agent-based IDE for working with files and projects. + It provides specialised editors for different file types — a WYSIWYG HTML editor, + a CodeMirror-backed code editor, and more editors to come — all within a + multi-panel, tab-based workspace. Projects can be hosted on the Roject server + (remote) or opened directly from the local filesystem (local), making it usable + both as a lightweight self-hosted CMS and as a full desktop development environment. + It is designed for individual developers or small teams and has no external database + dependency.
What still needs work
-
- This is a loose reminder, not a fixed backlog. Things we know are missing or
- incomplete: the Right panel has no default content and relies on manual tab
- dragging to populate; portrait mode's secondary section switcher
- (when a panel has multiple side-by-side sections) is not yet wired up; the
- member list UI shows raw UUIDs instead of usernames; the group editor and
- account delete button still use the browser confirm() instead of
- the custom dialog; non-text files (images, PDFs) in the tree are visible but
- not openable (a MediaViewerPanel is planned); and there is no
- real-time multi-user collaboration yet.
-
Items below are ordered by priority. Major planned features first, then smaller open improvements.
1 — Production server + CI
++ Deploy the Node.js/Express app to a publicly reachable server and wire up a + CI pipeline that builds, tests, and deploys automatically on push. The app's + file-based storage and no-database design make it straightforward to host on + any VPS: nginx as reverse proxy, PM2 or a systemd service for the Node.js + process. CI can run as a self-hosted Gitea/Forgejo Actions runner (matching + the existing self-hosted git remote) or mirror to GitHub Actions. This is + infrastructure work rather than feature work — it should be done once and early + because everything else ships faster and more safely once a real deployment + target and regression-catching pipeline exist. +
+ +2 — Electron desktop app + local filesystem access
++ Package Roject as a standalone desktop application using Electron. Since the + frontend is already plain HTML/JS/CSS, the Electron integration is mostly + structural: the Express server runs as a child process inside Electron's main + process, and the BrowserWindow is pointed at it. No frontend changes are needed + to make the existing UI run inside Electron. +
+
+ Local filesystem access follows from this almost for free: the file tree is
+ extended to browse arbitrary directories on the host machine using Node.js
+ fs directly, rather than being restricted to the
+ storage/<uuid>/root/ paths managed by the server. This is
+ what turns Roject from a hosted CMS into something closer to VS Code — the
+ user can open any folder on their machine as a project.
+
+ These two features are treated as a single unit of work: there is no point + shipping Electron without local filesystem access, and local filesystem access + in the browser would require the File System Access API with significant UX + friction. Electron is the cleaner path. +
+ +3 — Local git repository integration
++ Git integration inside the editor: file status indicators in the tree, staging, + commit, push and pull, and eventually diffs and history. This depends on local + filesystem access (feature 2) and follows naturally from it — once Roject can + open an arbitrary local directory, the git repo that directory belongs to is + already there. +
+
+ The implementation uses simple-git, a thin Node.js wrapper around
+ the git CLI, which keeps the dependency surface small and relies on the user's
+ existing git installation. An alternative is isomorphic-git (pure
+ JS, works in the browser too), but the CLI wrapper is simpler for a first
+ iteration. A new panel in the editor displays repo status and exposes the
+ common operations.
+
4 — Internet tunnel / port pass-through relay
++ A tunneling feature that allows local devices — a main workstation running + Stable Diffusion, a local LLM, a GDScript language server, or any other + service — to be accessible to authorised Roject users over the internet, + routed through the Roject server. +
++ The architecture: a small local agent (a Node.js script, or a built-in Roject + feature) connects to the Roject server via a persistent WebSocket, identifying + itself with a secret key. The server maps that key to a Roject user and + permission record. When an authorised Roject user (e.g. on their phone) makes + a request to the relay endpoint, the server forwards it through the WebSocket + to the local agent, which proxies it to the configured local port, and returns + the response the same way. +
++ The primary use case is mobile-to-desktop: use a phone as a thin client while + the main machine handles all heavy processing (image generation, inference, + language server completions). The secret key is the only credential needed — + it is registered once in Roject's user system and then shared with the local + agent. A single pass-through maps one local port to one authorised user. +
++ This feature is architecturally independent of Electron and mobile and lives + entirely on the server, so it can be developed in parallel with the desktop + work. It is placed here because its primary value is unlocked only once mobile + access (feature 5) also exists. +
+ +5 — Mobile app (PWA first, native shell later)
++ Make Roject usable on a phone or tablet. The quickest path given the existing + web frontend is a Progressive Web App (PWA) — a manifest file and a service + worker. This costs almost nothing to add, works in Safari and Chrome on both + Android and iOS without an app store, and covers the core use case of reaching + the editor and the tunnel relay from a mobile browser. +
++ If native capabilities are later needed (background processing, push + notifications, deeper OS integration), Capacitor can wrap the same web app + in a native shell without requiring a framework rewrite. A full React Native + or Flutter rewrite would be a significant departure from the existing Web + Components architecture and is not planned. +
++ The main challenge of a mobile editing experience is the code editor — CodeMirror + on a touchscreen is not great for authoring. The realistic mobile workflow is + lighter interaction: browsing files, reading output, triggering generation + requests through the tunnel relay, and simple edits rather than heavy coding. +
+ +Smaller open improvements
+-
+
- The Right panel has no default content and relies on manual tab dragging to populate. +
- Portrait mode's secondary section switcher (when a panel has multiple side-by-side sections) is not yet wired up. +
- The member list UI shows raw UUIDs instead of usernames. +
- The group editor and account delete button still use the browser
confirm()instead of the custom<confirm-dialog>.
+ - Non-text files (images, PDFs) are visible in the tree but not openable — a
MediaViewerPanelis planned.
+ - No real-time multi-user collaboration yet. +