185 lines
7.7 KiB
HTML
185 lines
7.7 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>Roject — Developer Documentation</title>
|
|
<link rel="stylesheet" href="../_assets_/styles.css">
|
|
<link rel="stylesheet" href="../_assets_/nav.css">
|
|
</head>
|
|
<body>
|
|
<div class="page">
|
|
|
|
<header>
|
|
<p class="date">Project Documentation</p>
|
|
<h1 style="font-size: 300%;">Roject</h1>
|
|
<p class="subtitle">Developer reference for human and agent contributors. Keep this file up to date as the project evolves.</p>
|
|
</header>
|
|
|
|
<section>
|
|
<h2>Project Outline</h2>
|
|
|
|
<div class="card">
|
|
<h3>What it is</h3>
|
|
<p>
|
|
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.
|
|
</p>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h3>What exists now</h3>
|
|
<p>
|
|
User accounts with registration, login, logout, and account deletion.
|
|
Groups and projects with member management (viewer / editor / admin roles).
|
|
Each project gets a real directory on disk at <code>storage/<uuid>/root/</code>
|
|
with a default <code>index.html</code> on creation.
|
|
</p>
|
|
<p style="margin-top:0.75rem">
|
|
A full editor page (<code>/editor.html</code>) with a 3-panel resizable layout
|
|
(Left / Center / Right). Each panel holds one or more sections side by side,
|
|
each section holds a <code><tab-container></code>. Tabs are draggable
|
|
between containers. The Left panel shows the file tree; the Center panel holds
|
|
the WYSIWYG HTML editor (iframe, <code>contenteditable</code>,
|
|
MutationObserver, undo/redo, Ctrl+S save). The Right panel is empty by default
|
|
and receives dropped tabs.
|
|
</p>
|
|
<p style="margin-top:0.75rem">
|
|
A reusable <code><confirm-dialog></code> component replaces browser
|
|
<code>confirm()</code> for destructive actions. Currently wired up for project
|
|
deletion only.
|
|
</p>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h3>What still needs work</h3>
|
|
<p>
|
|
This is a loose reminder, not a fixed backlog. Things we know are missing or
|
|
incomplete: a file manager inside the editor (create, rename, delete files and
|
|
folders from the tree); 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 <code>confirm()</code> instead of
|
|
the custom dialog; non-HTML files in the tree are visible but not openable;
|
|
and there is no real-time multi-user collaboration yet.
|
|
</p>
|
|
</div>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Technical Implementation</h2>
|
|
|
|
<div class="card">
|
|
<h3>Backend</h3>
|
|
<p>
|
|
Node.js + Express, TypeScript compiled on the fly with <code>ts-node</code>.
|
|
No database — all data lives as JSON files in <code>data/</code>
|
|
(auto-created on first run). Auth uses <code>express-session</code> +
|
|
<code>bcryptjs</code>. All entity IDs are UUIDs via
|
|
<code>crypto.randomUUID()</code> — no central counter, safe for parallel
|
|
instances. Start the server with <code>npm start</code>.
|
|
</p>
|
|
<div class="tags">
|
|
<span class="tag">Node.js</span>
|
|
<span class="tag">Express</span>
|
|
<span class="tag">ts-node</span>
|
|
<span class="tag">express-session</span>
|
|
<span class="tag">bcryptjs</span>
|
|
<span class="tag">UUID IDs</span>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h3>Frontend</h3>
|
|
<p>
|
|
Vanilla HTML, raw CSS (no Tailwind, no framework). Every UI component is a
|
|
custom element with its own <code>.ts</code> and <code>.css</code> file in
|
|
<code>src/components/<name>/</code>. CSS uses the element tag as root
|
|
selector with <code>display: block</code>. TypeScript compiles to
|
|
<code>public/components/</code> via <code>tsconfig.client.json</code>
|
|
(<code>module: ESNext</code>, <code>moduleResolution: bundler</code>, no
|
|
bundler). HTML pages load components with
|
|
<code><script type="module"></code>. Shared state uses a module-level
|
|
singleton (<code>editor-state.ts</code>) rather than globals.
|
|
Build with <code>npm run build</code>.
|
|
</p>
|
|
<div class="tags">
|
|
<span class="tag">Web Components</span>
|
|
<span class="tag">raw CSS</span>
|
|
<span class="tag">module: ESNext</span>
|
|
<span class="tag">no bundler</span>
|
|
<span class="tag">tsc --build</span>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h3>Shared Library</h3>
|
|
<p>
|
|
A personal TypeScript library lives as a git submodule at
|
|
<code>src/library-ts/</code>. It has two parts: <code>browser/</code>
|
|
(DOM-capable) and <code>node/</code> (Node.js only). The browser part is
|
|
compiled separately via TypeScript project references
|
|
(<code>src/library-ts/browser/tsconfig.roject.json</code>, <code>strict: false</code>)
|
|
into <code>public/library-ts/browser/</code>. The node part is included by
|
|
<code>tsconfig.ts-node.json</code> (extends server config, <code>strictNullChecks: false</code>).
|
|
</p>
|
|
<div class="tags">
|
|
<span class="tag">git submodule</span>
|
|
<span class="tag">src/library-ts/</span>
|
|
<span class="tag">project references</span>
|
|
<span class="tag">composite: true</span>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h3>Locales</h3>
|
|
<p>
|
|
All user-visible strings are stored as plain files under <code>locales/en/</code>
|
|
and accessed in code via <code>LocaleManager.$.get( Locales.X.Y.member_ext )</code>.
|
|
Never hardcode a user-visible string directly in TypeScript.
|
|
<br>
|
|
<a href="locales/index.html">Read more about the locale system</a>
|
|
</p>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h3>Guides</h3>
|
|
<p>
|
|
Reference guides for working in specific areas of the project.
|
|
Read the relevant guide before starting a task in that area.
|
|
<br>
|
|
<a href="../guides/index.html">Browse all guides</a>
|
|
</p>
|
|
<ul style="margin-top:0.75rem">
|
|
<li><strong>Writing code</strong> → <a href="../guides/writing-typescript-code/index.html">Writing TypeScript Code</a></li>
|
|
<li><strong>Adding user-visible strings</strong> → <a href="../guides/locales/index.html">Locales</a></li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h3>Actions</h3>
|
|
<p>
|
|
Repeatable procedures for maintaining the project.
|
|
<br>
|
|
<a href="../actions/index.html">Browse all actions</a>
|
|
</p>
|
|
<ul style="margin-top:0.75rem">
|
|
<li><strong>End of session</strong> → <a href="../actions/update-history/index.html">Update History</a>, <a href="../actions/update-outline/index.html">Update Outline</a></li>
|
|
</ul>
|
|
</div>
|
|
</section>
|
|
|
|
<footer>
|
|
Roject — developer documentation
|
|
</footer>
|
|
|
|
</div>
|
|
<script>var NAV_ROOT = '../';</script>
|
|
<script src="../_assets_/nav-data.js"></script>
|
|
<script src="../_assets_/nav.js"></script>
|
|
</body>
|
|
</html>
|