# Spaces Architecture

> Spaces Architecture is an Agent Skill for development published in the massCodeIO/massCode repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when working on massCode spaces such as code, notes, math, or tools, especially when changing their state, behavior, synchronization, or spaces IPC channels.

- Skill name: `spaces-architecture`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/massCodeIO/massCode/blob/HEAD/.agents/skills/spaces-architecture/SKILL.md
- Repository: massCodeIO/massCode (6,919 GitHub stars when collected)

## SKILL.md

# Spaces Architecture

## Overview

massCode использует систему Spaces для разделения функциональных областей. Это не просто UI tabs: у каждого space есть собственное состояние, свои правила обновления и свой способ синхронизации с данными в vault.

## Space Model

- `code` — snippets, folders, tags
- `notes` — notes, folders, tags, markdown-based flows
- `math` — calculation sheets и состояние math notebook
- `tools` — developer utilities

Основные определения живут в `src/renderer/spaceDefinitions.ts`.

## Space State Storage

- Состояние каждого space хранится в `__spaces__/{spaceId}/.state.yaml` внутри vault.
- Runtime helpers:
  - `src/main/storage/providers/markdown/runtime/spaces.ts`
  - `src/main/storage/providers/markdown/runtime/spaceState.ts`
- Директория `__spaces__/` — служебная часть vault для состояния spaces.

## Persistence Rules

- Запись состояния spaces использует ту же debounce/flush инфраструктуру, что и `state.json`.
- Не ломай совместимость с `pendingStateWriteByPath` и flush-on-exit поведением.
- Если меняешь способ записи, учитывай сценарий завершения приложения до явного ручного flush.

## IPC Rules

- Space-specific IPC handlers живут в `src/main/ipc/handlers/spaces.ts`.
- Текущие math handlers:
  - `spaces:math:read`
  - `spaces:math:write`
- Если добавляется новый `spaces:*` flow, он должен работать через общую модель состояния spaces, а не в обход неё.

## Space-Aware Sync

- `system:storage-synced` обновляет активное пространство через `getActiveSpaceId()`.
- Ожидаемое поведение:
  - `code` → refresh folders + snippets
  - `notes` → refresh notes + note folders
  - `math` → `reloadFromDisk()` через `useMathNotebook()`
  - `tools` → no-op
- Изменения, которые уже сохранены в vault, должны вызывать `markPersistedStorageMutation()`, чтобы не создавать sync loops.

## Common Mistakes

- Считать spaces только UI-концепцией и забывать, что у них есть собственное состояние и правила синхронизации.
- Писать состояние space в обход общих markdown runtime helpers.
- Добавлять mutation без `markPersistedStorageMutation()`.
- Ломать согласованность между состоянием space, helpers и sync behavior.

---

Source: https://www.openparable.com/skill/development/spaces-architecture (OpenParable). Cite the canonical URL above.
