CodeView FSD Architecture

Visual Feature-Sliced Design (FSD) business map for VS Code. CodeView reads a .codeview config in your workspace root and shows slices grouped by FSD layers. Edit in the UI or in the file — changes stay in sync.

You can also generate .codeview from a product brief using Claude Code or the Cursor SDK.

Features

• FSD layer board (app, processes, pages, widgets, features, entities, shared)
• Slice cards with short name, title, optional description, optional code links, and optional tag
• Welcome guide when the map is empty; reopen anytime via the Info icon
• Two-way sync between .codeview and the panel (file watcher + UI save)
• AI generation from a business brief (code-aware links from the workspace when possible)
• Creating or editing a slice triggers AI refresh of that slice’s code links
• Agent task + on a slice: scoped coding task that starts from the slice’s links
• Remove individual links from the Links modal (trash icon)

Prerequisites

• VS Code 1.85+
• An open workspace folder (File → Open Folder)
• For Generate → Cursor: Cursor API key in settings or CURSOR_API_KEY env
• For Generate → Claude: Claude Code CLI (claude on PATH)

Usage

1. Open a project folder in VS Code.
2. Run CodeView: Open Panel (codeview.openPanel) from the Command Palette.
3. If the map is empty, the welcome guide explains Generate vs Create. Later: Info (help icon), Generate in the header, + FAB to add a slice.
4. View slices in layer columns (empty layers are hidden). Click a slice to edit; saving a changed slice refreshes its code links via AI.
5. Use Agent task + on a card to run a scoped AI coding task (starts from that slice’s links). Summary appears in Output → CodeView Agent Task.
6. Edit .codeview in the editor — the panel updates automatically.
7. Open a slice’s links from the card icon; remove a link with the trash button.

Generate .codeview

Describe your product (roles, flows, domains), not your repository tree.

Primary flow: CodeView: Open Panel → Generate in the header (or on the welcome guide). Add slices with the + button.

Optional: Command Palette → CodeView: Generate .codeview (same pipeline, without opening the panel first).

Agent task (scoped coding)

On any slice card, click Agent task +, choose provider, and describe the change (new widget behavior, remove a feature, adjust validation, etc.).

The agent receives only that slice’s context plus its links, and is instructed to start there — tighter than a whole-repo brief. Attach good links first for better results and fewer tokens.

When finished, open Output → CodeView Agent Task for the short summary.

Settings (optional defaults):

Cursor API key is not shown in the Generate modal. Supported ways to provide it:

1. Setting codeview.gen.cursorApiKey in VS Code / Cursor settings (preferred for local use)
2. Process environment variable CURSOR_API_KEY (must be available to the IDE process)
3. Command args cursorApiKey (keybindings / automation)

A .env file in the consumer project is not loaded automatically by the extension.

Full generate docs: docs/gen-webview.md.

.codeview format

Example:

{
  "tags": ["auth", "billing"],
  "data": [
    {
      "id": "login-form",
      "title": "login-form",
      "name": "Login form",
      "layer": "features",
      "tag": "auth",
      "description": "Sign-in form for email and password, with validation and error feedback.",
      "links": [
        {
          "path": "src/features/auth",
          "label": "auth feature",
          "kind": "folder"
        },
        {
          "path": "src/features/auth/ui/LoginForm.tsx",
          "label": "login UI",
          "kind": "file",
          "line": 1
        }
      ]
    }
  ]
}

• data — required array of slices (id, title, layer, optional name, tag, description, links)
• name — short human-readable label in the brief’s language (about 2–5 words); shown as the primary card heading
• title — kebab-case slice id shown secondary on the card
• description — short business summary in the user’s language; optional
• links — optional code anchors (path, optional label / line / kind: file | folder); open from the card icon, remove with trash in the Links modal. After Create or Edit (when business fields change), AI replaces that slice’s links from the workspace
• tags — optional list for tag selects
• layers — optional custom layer list; omit to use default FSD layers

Custom layers

If layers is omitted or empty, CodeView uses the default FSD board:

app → processes → pages → widgets → features → entities → shared

To override architecture, put a non-empty layers array in .codeview (edit the file; there is no layers UI). Board columns follow that list. Every data[].layer must match a layers[].name.

Custom layers should reflect business / domain structure, not tech folders. Example:

{
  "layers": [
    { "name": "domain", "color": "#5c6bc0" },
    { "name": "application", "color": "#66bb6a" },
    { "name": "infrastructure", "color": "#78909c" }
  ],
  "data": [
    {
      "id": "checkout",
      "title": "checkout",
      "name": "Checkout",
      "layer": "application",
      "description": "Checkout flow for cart review, payment method, and order confirmation."
    }
  ]
}

On Generate, if .codeview already exists, the model is instructed to reconcile with the previous map: keep items when changes are minor, update only for meaningful business differences.

Schema: schemas/codeview.schema.json.

Development

npm install
npm run dev

1. Press F5 to open the Extension Development Host.
2. In that window: File → Open Folder (required for .codeview read/write).
3. Run CodeView: Open Panel.
4. After UI (src/webview) changes: close and reopen the panel (or reload the window).
5. After extension host changes: reload the Extension Development Host.

Scripts

Package locally

npm run package

Install the resulting codeview-fsd-*.vsix via Extensions → … → Install from VSIX….

Publish to VS Code Marketplace

1. Create a publisher. The publisher id must match "publisher" in package.json (currently Irinova).
2. Create an Azure DevOps Personal Access Token with scope Marketplace → Manage.
3. Log in and publish:

npx vsce login Irinova
npm run publish:vsce

Use npm run publish:patch (or publish:minor / publish:major) to bump the version.

Pre-release checklist

• npm run typecheck && npm run build && npm run package
• Bump version in package.json
• README and icon are up to date
• Test in Extension Development Host with an open folder

Release scripts

Project structure

codeview/
├── images/icon.png        # Marketplace icon
├── prompts/               # AI prompt template
├── schemas/               # JSON Schema for .codeview
├── src/
│   ├── extension.ts
│   ├── generateCommand.ts
│   ├── configSync.ts
│   ├── gen/               # Shared generate pipeline
│   └── webview/           # React UI
├── dist/                  # Built extension + webview
└── docs/gen-webview.md

License

MIT