Start9/start-os
2
0
Fork 0
mirror of https://github.com/Start9Labs/start-os.git synced 2026-03-26 02:11:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update ARCHITECTURE.md and CLAUDE.md for Angular 21 + Taiga UI 5

Browse Source 
Update version references from Angular 20 to Angular 21 and Taiga UI to
Taiga UI 5 across architecture docs. Update web/CLAUDE.md with improved
Taiga golden rules: prioritize MCP server for docs, remove hardcoded
component examples in favor of live doc lookups.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Matt Hill
2026-03-15 21:43:34 -06:00
parent b5ac0b5200
commit ebb7916ecd
3 changed files with 15 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
ARCHITECTURE.md
View File

@@ -5,7 +5,7 @@ StartOS is an open-source Linux distribution for running personal servers. It ma
## Tech Stack
- Backend: Rust (async/Tokio, Axum web framework)
- Frontend: Angular 20 + TypeScript + TaigaUI
- Frontend: Angular 21 + TypeScript + Taiga UI 5
- Container runtime: Node.js/TypeScript with LXC
- Database/State: Patch-DB (git submodule) - storage layer with reactive frontend sync
- API: JSON-RPC via rpc-toolkit (see `core/rpc-toolkit.md`)
@@ -30,7 +30,7 @@ StartOS is an open-source Linux distribution for running personal servers. It ma
- **`core/`** — Rust backend daemon. Produces a single binary `startbox` that is symlinked as `startd` (main daemon), `start-cli` (CLI), `start-container` (runs inside LXC containers), `registrybox` (package registry), and `tunnelbox` (VPN/tunnel). Handles all backend logic: RPC API, service lifecycle, networking (DNS, ACME, WiFi, Tor, WireGuard), backups, and database state management. See [core/ARCHITECTURE.md](core/ARCHITECTURE.md).
- **`web/`** — Angular 20 + TypeScript workspace using Taiga UI. Contains three applications (admin UI, setup wizard, VPN management) and two shared libraries (common components/services, marketplace). Communicates with the backend exclusively via JSON-RPC. See [web/ARCHITECTURE.md](web/ARCHITECTURE.md).
- **`web/`** — Angular 21 + TypeScript workspace using Taiga UI 5. Contains three applications (admin UI, setup wizard, VPN management) and two shared libraries (common components/services, marketplace). Communicates with the backend exclusively via JSON-RPC. See [web/ARCHITECTURE.md](web/ARCHITECTURE.md).
- **`container-runtime/`** — Node.js runtime that runs inside each service's LXC container. Loads the service's JavaScript from its S9PK package and manages subcontainers. Communicates with the host daemon via JSON-RPC over Unix socket. See [container-runtime/CLAUDE.md](container-runtime/CLAUDE.md).

2
web/ARCHITECTURE.md
View File

@@ -1,6 +1,6 @@
# Web Architecture
Angular 20 + TypeScript workspace using [Taiga UI](https://taiga-ui.dev/) component library.
Angular 21 + TypeScript workspace using [Taiga UI 5](https://taiga-ui.dev/) component library.
## API Layer (JSON-RPC)

77
web/CLAUDE.md
View File

@@ -1,6 +1,6 @@
# Web — Angular Frontend
Angular 20 + TypeScript workspace using [Taiga UI](https://taiga-ui.dev/) component library.
Angular 21 + TypeScript workspace using [Taiga UI 5](https://taiga-ui.dev/) component library.
## Projects
@@ -21,15 +21,22 @@ npm run check # Type check all projects
## Golden Rules
1. **Taiga-first.** Use Taiga components, directives, and APIs whenever possible. Avoid hand-rolled HTML/CSS unless absolutely necessary. If Taiga has a component for it, use it.
1. **Taiga does it all.** We use Taiga UI 5 for everything — components, directives, layout, dialogs, forms, icons, and styling. Do not hand-roll HTML/CSS when Taiga provides a solution. If you think Taiga can't do something, you're probably wrong — look it up first.
2. **Pattern-match.** Nearly anything we build has a similar example elsewhere in this codebase. Search for existing patterns before writing new code. Copy the conventions used in neighboring components.
2. **Follow existing patterns.** Before writing new code, search this codebase for a similar example. Nearly anything we build has a precedent. Copy the conventions used in neighboring components. Do not invent new patterns when established ones exist.
3. **When unsure about Taiga, ask or look it up.** Use `WebFetch` against `https://taiga-ui.dev/llms-full.txt` to search for component usage, or ask the user. Taiga docs are authoritative. See [Taiga UI Docs](#taiga-ui-docs) below.
3. **Never guess Taiga APIs.** Taiga UI 5 has its own way of doing things. Do not make up component names, directive names, input bindings, or usage patterns from memory. Always verify against the official docs or the MCP server. Getting it wrong wastes everyone's time.
4. **Use the Taiga MCP server.** If a `taiga-ui-mcp` MCP server is available, use it to look up components and get documentation with code examples. It provides two tools: `get_list_components` (search/filter components) and `get_component_example` (get full docs and examples for a component). This is the fastest and most accurate way to get Taiga usage information.
5. **Fall back to the Taiga docs.** If the MCP server is not available, use `WebFetch` against `https://taiga-ui.dev/llms-full.txt` to search for component usage. Taiga docs are authoritative — this project's code is not. See [Taiga UI Docs](#taiga-ui-docs) below.
## Taiga UI Docs
Taiga provides an LLM-friendly reference at `https://taiga-ui.dev/llms-full.txt` (~2200 lines covering all components with code examples). Use `WebFetch` to search it when you need to look up a component, directive, or API:
Taiga provides AI-friendly references at [taiga-ui.dev/ai-support](https://taiga-ui.dev/ai-support):
- **MCP server** — [`taiga-ui-mcp`](https://github.com/taiga-family/taiga-ui-mcp) provides full access to Taiga UI component docs and Angular code examples via the Model Context Protocol.
- **llms-full.txt** — `https://taiga-ui.dev/llms-full.txt` (~2200 lines covering all components with code examples). Use `WebFetch` to search it:
```
WebFetch url=https://taiga-ui.dev/llms-full.txt prompt="How to use TuiTextfield with a select dropdown"
@@ -50,63 +57,3 @@ See [ARCHITECTURE.md](ARCHITECTURE.md) for the web architecture: API layer, Patc
- **`toSignal()`** to convert Observables (e.g., PatchDB watches) to signals.
- **`ChangeDetectionStrategy.OnPush`** on almost all components.
- **`takeUntilDestroyed(inject(DestroyRef))`** for subscription cleanup.
## Common Taiga Patterns
### Textfield + Select (dropdown)
```html
<tui-textfield tuiChevron>
<label tuiLabel>Label</label>
<input tuiSelect />
<tui-data-list *tuiTextfieldDropdown>
<button tuiOption [value]="item" *ngFor="let item of items">{{ item }}</button>
</tui-data-list>
</tui-textfield>
```
Provider to remove the X clear button:
```typescript
providers: [tuiTextfieldOptionsProvider({ cleaner: signal(false) })]
```
### Buttons
```html
<button tuiButton appearance="primary">Submit</button>
<button tuiButton appearance="secondary">Cancel</button>
<button tuiIconButton appearance="icon" iconStart="@tui.trash"></button>
```
### Dialogs
```typescript
// Confirmation
this.dialog.openConfirm({ label: 'Warning', data: { content: '...', yes: 'Confirm', no: 'Cancel' } })
// Custom component in dialog
this.dialog.openComponent(new PolymorpheusComponent(MyComponent, injector), { label: 'Title' })
```
### Toggle
```html
<input tuiSwitch type="checkbox" size="m" [showIcons]="false" [(ngModel)]="value" />
```
### Errors & Tooltips
```html
<tui-error formControlName="controlName" />
<tui-error [error]="'Error text'" />
<tui-icon [tuiTooltip]="'Hint text'" />
```
### Layout
```html
<tui-elastic-container><!-- dynamic height --></tui-elastic-container>
<tui-scrollbar><!-- scrollable content --></tui-scrollbar>
<tui-loader [textContent]="'Loading...' | i18n" />
```