# Spaces Architecture

> 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: `masscodeio/spaces-architecture` (Agent Skill)
- Install (CLI): `npx skillmds@latest add masscodeio/spaces-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/masscodeio/spaces-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: masscodeio (https://skillmd.com/u/masscodeio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/masscodeio/spaces-architecture

---


# 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.