Selise Blocks Development

Expert guidance for Claude Code when working with Selise Blocks applications, including FastMCP server integration, schema management, translation workflows, and the vibecoding experience.

Critical: Read Documentation First

**MANDATORY: Before ANY implementation, you MUST read the project's llm-docs/ directory IN ORDER:**

1. `workflows/user-interaction.md` - User communication patterns

2. `workflows/feature-planning.md` - Task breakdown and planning

3. `recipes/graphql-crud.md` - Data operations (NOT inventory patterns!)

4. `recipes/translation-integration.md` - Translation process and route mapping

5. `agent-instructions/selise-development-agent.md` - Development workflows

6. Other recipes as needed for specific features

**If llm-docs/ is not found, perform a full directory search before proceeding.**

MCP Server Integration

This project uses a FastMCP (Model Context Protocol) server for automating Selise Cloud operations. MCP tools MUST be used for all project setup and schema management.

Available MCP Tools

**Authentication:**

**Project Management:**

**Schema Management:**

**Translation Management:**

**Other Tools:**

Project Key Configuration

**CRITICAL: Always get the project key from environment variables before using MCP tools.**

```bash

For default environment

PROJECT_KEY=$(grep VITE_X_BLOCKS_KEY .env | cut -d '=' -f2)

For specific environment (e.g., dev)

PROJECT_KEY=$(grep VITE_X_BLOCKS_KEY .env.dev | cut -d '=' -f2)

```

Vibecoding Experience Flow

**MUST FOLLOW IN ORDER when user wants to create any webapp/website:**

1. Read Documentation (Before Talking to User)

2. User Interaction & Requirements Gathering

3. Feature Planning & Schema Design (After User Confirmation)

```python

For each entity the app needs:

create_schema(

schema_name="<projectName>Tasks",

fields=[

{"name": "Title", "type": "String"},

{"name": "Status", "type": "String"},

{"name": "Point", "type": "Float"},

{"name": "Priority", "type": "Int"}

]

)

```

4. Static Content Translation Workflow

**AFTER implementing new features with static text, MUST translate all user-facing strings using MCP translation tools.**

**Complete instructions**: See `llm-docs/recipes/translation-integration.md`

**Quick checklist:**

5. Implementation Process

**Step 1: Work from TASKS.md**

**Step 2: Frontend Implementation**

**Step 3: Testing & Quality**

**Step 4: Sidebar Management (CRITICAL)**

**DEFAULT: Hide ALL sidebar items - start with clean slate!**

```typescript

// By default, REMOVE or HIDE all existing sidebar items

// Only add navigation if the app actually needs it

// Option 1: No sidebar at all (most apps)

// Just remove AppSidebar component entirely

// Option 2: Custom sidebar (only if needed)

// If user's app needs navigation:

// 1. Hide ALL default items (inventory, IAM, etc.)

// 2. Add ONLY items for user's features

// 3. Example for task management app:

const sidebarItems = [

{ label: 'Dashboard', path: '/dashboard', icon: 'home' },

{ label: 'Tasks', path: '/tasks', icon: 'list' },

{ label: 'Settings', path: '/settings', icon: 'settings' },

];

// Remove ALL demo/template items!

```

**Never show irrelevant items like inventory, invoices, IAM unless user specifically requested those features!**

**Step 5: Git Workflow**

```bash

Branch for each feature

git checkout -b feature/[task-name]

After implementation

git add .

git diff --staged # Review changes

Update tracking files before commit:

- Mark task complete in TASKS.md: [x]

- Add notes to SCRATCHPAD.md

- Update FEATURELIST.md if scope changed

- Document schema changes in CLOUD.md

Compliance checklist:

- Used MCP for schema creation?

- Followed 3-layer hierarchy?

- Used AdvanceDataTable for tables?

- Used ConfirmationModal for confirmations?

- Followed recipes from llm-docs?

- Updated TASKS.md with completion status?

git commit -m "feat: implement [task] using MCP and Selise patterns

git checkout main

git merge feature/[task-name]

```

Architecture & Patterns

Core Stack

Feature Structure (MUST FOLLOW)

**Directory Structure - Follow inventory pattern:**

```

src/modules/[modules-name]/

├── components/ # Feature-specific components

├── graphql/ # Queries and mutations (if using GraphQL)

├── hooks/ # Feature-specific hooks

├── services/ # API calls and business logic

├── types/ # TypeScript interfaces

└── index.ts # Public exports

```

**CRITICAL: Inventory is for STRUCTURE ONLY, not data operations!**

Component Hierarchy (3-Layer Rule)

```

1. Feature Components (src/modules/*/components/)

2. Block Components (src/components/core/)

3. UI Components (src/components/ui/)

```

Critical Patterns from Recipes

**GraphQL Operations (from graphql-crud.md - NOT inventory!)**

**CRITICAL QUIRKS - MUST KNOW:**

**Data Tables (from data-table-with-crud-operations.md)**

**Forms (from react-hook-form-integration.md)**

**Confirmations (from confirmation-modal-patterns.md)**

Common Pitfalls to Avoid

1. **DON'T** look for existing domains - always create new project

2. **DON'T** create schemas manually - use MCP tools

3. **DON'T** skip reading recipes before implementation

4. **DON'T** create custom components when Selise components exist

5. **DON'T** use Apollo Client - use graphqlClient from recipes

6. **DON'T** bypass the 3-layer component hierarchy

7. **DON'T** copy GraphQL patterns from inventory - use recipes/graphql-crud.md

Implementation Checklist

Before ANY implementation:

Quick Start Commands

```bash

After MCP project creation

cd [project-name]

npm install

npm start

Development

npm run lint # Check code quality

npm test # Run tests

npm run build # Production build

```

Priority Documentation

When conflicts arise, follow this priority:

1. **MCP tool usage** (MCP section above)

2. **Recipes** (llm-docs/recipes/)

3. **Component hierarchy** (llm-docs/component-catalog/)

4. **General patterns** (other docs)

**Remember**: MCP automation takes precedence over manual processes. Always use MCP tools for project setup, authentication, and schema management.