Selise Blocks Development Guide

This skill provides complete guidance for developing Selise Blocks applications using FastMCP (Model Context Protocol) server integration. It enforces a structured workflow from requirements gathering to implementation.

🚨 Critical Requirements

1. MCP Server Integration

This project REQUIRES the FastMCP server for all Selise Cloud operations. MCP tools are MANDATORY for project setup and schema management.

2. Documentation-First Approach

**BEFORE ANY IMPLEMENTATION**, read these files IN ORDER:

```

llm-docs/

├── workflows/

│ ├── user-interaction.md # Read FIRST - User interaction patterns

│ └── feature-planning.md # Read SECOND - Task breakdown

├── recipes/ # CRITICAL implementation patterns

│ ├── graphql-crud.md # ONLY source for data operations

│ ├── translation-integration.md # Translation process

│ ├── react-hook-form-integration.md

│ └── confirmation-modal-patterns.md

├── component-catalog/ # Component hierarchy rules

│ ├── component-quick-reference.md

│ └── selise-component-hierarchy.md

└── agent-instructions/ # Development workflows

```

3. Project Key Configuration

**ALWAYS get project key from environment variables:**

```bash

Default environment

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

Specific environment

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

```

Development Workflow

Step 1: Read Documentation (Before User Interaction)

1. Read `workflows/user-interaction.md`

2. Read `workflows/feature-planning.md`

3. Read `agent-instructions/selise-development-agent.md`

Step 2: User Interaction & Requirements Gathering

1. Follow patterns from `user-interaction.md`

2. Create tracking files:

- `FEATURELIST.md` - All features user wants

- `TASKS.md` - Technical tasks breakdown

- `SCRATCHPAD.md` - Development notes

- `CLOUD.md` - MCP operations log

3. Ask clarifying questions about features

4. Document everything in FEATURELIST.md

5. **GET USER CONFIRMATION** before proceeding

Step 3: Feature Planning & Schema Design

**Only proceed after user confirmation of FEATURELIST.md**

1. Break down features into technical requirements

2. Analyze required schemas based on FEATURELIST.md

3. Document schema plan in CLOUD.md

4. Use MCP authentication first:

```python

# Check auth status

get_auth_status()

```

5. Create schemas using MCP:

```python

create_schema(

schema_name="<ProjectName><EntityName>",

fields=[

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

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

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

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

]

)

# Verify schema creation

list_schemas()

get_schema_details(schema_name="<ProjectName><EntityName>")

```

6. Document all MCP operations in CLOUD.md

Step 4: Frontend Implementation

1. **Work from TASKS.md** - update task status: `[ ]` → `[🔄]` → `[x]`

2. **Follow 3-Layer Component Hierarchy:**

```

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

↓

Block Components (src/components/core/)

↓

UI Components (src/components/ui/)

```

3. **Use Directory Structure from Inventory:**

```

src/modules/[module-name]/

├── components/

├── graphql/

├── hooks/

├── services/

├── types/

└── index.ts

```

4. **GraphQL Operations (CRITICAL):**

- **NEVER copy inventory GraphQL patterns**

- **ONLY follow `recipes/graphql-crud.md`**

- Get schema names from MCP first: `list_schemas()` and `get_schema_details()`

- Query fields: SchemaName + 's' (TodoTask → TodoTasks)

- Mutations: operation + SchemaName (insertTodoTask)

- ALWAYS use MongoDB filter: `JSON.stringify({_id: "123"})`

- Use `graphqlClient` from `lib/graphql-client`, NEVER Apollo Client

- Response path: `result.[SchemaName]s.items`

5. **Required Patterns:**

- **Tables**: ALWAYS use AdvanceDataTable component

- **Forms**: React Hook Form + Zod validation (see `react-hook-form-integration.md`)

- **Confirmations**: ALWAYS use ConfirmationModal (see `confirmation-modal-patterns.md`)

6. **Update TASKS.md** as you complete components

Step 5: Translation Integration

**AFTER implementing features with static text:**

1. Read `llm-docs/recipes/translation-integration.md`

2. Extract ALL hardcoded strings to translation keys

3. Add route mapping in `src/i18n/route-module-map.ts`

4. Create translation module using MCP:

```python

create_module(module_name="<route-name>")

```

5. Add translations using MCP:

```python

save_module_keys_with_translations(

module_name="<route-name>",

keys_with_translations=[

{

"key": "page.title",

"translations": [

{"language": "en", "translation": "Page Title"},

{"language": "bn", "translation": "পৃষ্ঠার শিরোনাম"}

]

}

]

)

```

6. Test translation loading on route

7. Document keys in TASKS.md

Step 6: Sidebar Management

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

```typescript

// Option 1: No sidebar (most apps)

// Remove AppSidebar component entirely

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

// 1. Hide ALL default items

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

const sidebarItems = [

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

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

];

// NEVER show irrelevant items (inventory, IAM, etc.)

```

Step 7: Testing & Quality

1. Run linting: `npm run lint`

2. Run tests: `npm test`

3. Test all CRUD operations

4. Mark tasks complete in TASKS.md

Step 8: Git Workflow

```bash

Create feature branch

git checkout -b feature/[task-name]

Review changes

git add .

git diff --staged

Update tracking files before commit:

- Mark task [x] in TASKS.md

- Add notes to SCRATCHPAD.md

- Update FEATURELIST.md if needed

- Document schema changes in CLOUD.md

Compliance checklist:

✓ Used MCP for schemas?

✓ Followed 3-layer hierarchy?

✓ Used AdvanceDataTable?

✓ Used ConfirmationModal?

✓ Followed recipes?

✓ Updated TASKS.md?

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

git checkout main

git merge feature/[task-name]

```

MCP Tools Reference

Authentication

Project Management

Schema Management

Translation Management

Other

Core Stack

Common Pitfalls to Avoid

1. ❌ DON'T skip reading llm-docs before implementation

2. ❌ DON'T copy inventory GraphQL patterns - use recipes/graphql-crud.md

3. ❌ DON'T create schemas manually - use MCP tools

4. ❌ DON'T create custom table components - use AdvanceDataTable

5. ❌ DON'T use Apollo Client - use graphqlClient

6. ❌ DON'T bypass 3-layer component hierarchy

7. ❌ DON'T show irrelevant sidebar items

8. ❌ DON'T start implementation without user confirmation of FEATURELIST.md

Pre-Implementation Checklist

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

```

Documentation Priority

When conflicts arise:

1. MCP tool usage (this guide's MCP section)

2. Recipes (llm-docs/recipes/)

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

4. General patterns (other docs)

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