@cdmbase/wiki-browser 12.0.18-alpha.5

package/lib/templates/content/docs/LLM/organization-components-form-llm.md

@@ -0,0 +1,1395 @@
+# 🎨 Frontend: Organization-Scoped Form Creation Guide
+
+## Overview
+
+This guide covers creating React forms that work with organization-scoped entities in the AdminIDE stack. The pattern ensures proper organization context is maintained throughout the form lifecycle, from data fetching to mutations.
+
+**Use this guide when creating forms for entities that belong to an organization (Tags, Projects, Vaults, etc.)**
+
+## 🔑 Core Principles
+
+1. **Organization from Route Parameters**: Extract `orgName` from URL params
+2. **GraphQL Variables**: Pass `orgName` to all queries requiring organization context
+3. **State Management**: Use XState machines for complex form workflows
+4. **Type Safety**: Leverage generated GraphQL types from `common/graphql`
+5. **Error Handling**: Handle partial data gracefully with error policies
+
+---
+
+## 📋 Complete Frontend Implementation Pattern
+
+### **Step 1: React Component Structure**
+
+```tsx
+// TagsView.tsx - Organization-scoped entity management
+import React, { useState } from 'react';
+import { useMachine } from '@xstate/react';
+import { fromPromise } from 'xstate';
+import { useLoaderData, useParams } from '@remix-run/react';
+import {
+    useCreateTagMutation,
+    useRemoveTagMutation,
+    useGetTagsQuery,
+    useUpdateTagMutation,
+    useGetTagTypesQuery,
+    useGetProjectsQuery,
+} from 'common/graphql';
+import { tagsMachine, Tag } from '../tagsMachine';
+
+export default function TagsView() {
+    // 🔑 CRITICAL: Extract organization from route params
+    const { orgName } = useParams<{ orgName: string }>();
+    const loaderData: any = useLoaderData();
+    const userId = loaderData.dataContext.userId;
+
+    // 🔑 CRITICAL: GraphQL Queries with orgName variable
+    const {
+        data: tagsData,
+        refetch: tagsRefetch,
+        loading: tagsLoading,
+        error: tagsError,
+    } = useGetTagsQuery({
+        variables: { orgName }, // Pass organization context
+        errorPolicy: 'all', // Allow partial data
+    });
+
+    const { data: projectsData, error: projectsError } = useGetProjectsQuery({
+        variables: { orgName }, // Organization context required
+        fetchPolicy: 'cache-only',
+        errorPolicy: 'all',
+    });
+
+    const { data: tagTypesData, error: tagTypesError } = useGetTagTypesQuery({
+        errorPolicy: 'all',
+    });
+
+    // 🔑 GraphQL Mutations
+    const [createTag] = useCreateTagMutation();
+    const [updateTag] = useUpdateTagMutation();
+    const [removeTag] = useRemoveTagMutation();
+
+    // Toast notifications for UX feedback
+    const [toast, setToast] = useState({ show: false, message: '', type: '' });
+
+    // 🔑 XState Machine with actor implementations
+    const [state, send] = useMachine(
+        tagsMachine.provide({
+            actors: {
+                // Fetch actor - loads tags from query data
+                fetchTags: fromPromise(async () => {
+                    const tags = tagsData?.getTags?.data || [];
+                    // Filter out null/invalid entries
+                    return tags.filter((tag) => tag && tag.id);
+                }),
+
+                // Fetch related data
+                fetchProjects: fromPromise(async () => {
+                    const projects = projectsData?.getProjects?.data || [];
+                    return projects.filter((project) => project && project.id);
+                }),
+
+                fetchTagTypes: fromPromise(async () => {
+                    const tagTypes = tagTypesData?.getTagTypes || [];
+                    return tagTypes.filter((tagType) => tagType && tagType.id);
+                }),
+
+                // Submit actor - creates new tag
+                submitTag: fromPromise(async ({ input }) => {
+                    const { tag } = input;
+
+                    // Client-side validation
+                    if (!tag.project?.id || !tag.tagType?.id) {
+                        setToast({
+                            show: true,
+                            message: 'Please select both a project and a tag type',
+                            type: 'error',
+                        });
+                        setTimeout(() => setToast({ show: false, message: '', type: '' }), 3000);
+                        throw new Error('Project and tag type must be selected.');
+                    }
+
+                    // 🔑 CRITICAL: Create mutation
+                    // Note: organization context comes from backend @addAccountContext
+                    // No need to pass orgName/orgId in mutation variables
+                    const response = await createTag({
+                        variables: {
+                            request: {
+                                projectId: tag.project.id,
+                                tagTypeId: tag.tagType.id,
+                                name: tag.name,
+                                description: tag.description || '',
+                                createdBy: userId,
+                            },
+                        },
+                        update: (cache, { data, errors }) => {
+                            if (data) {
+                                setToast({
+                                    show: true,
+                                    message: 'Tag has been created!',
+                                    type: 'success',
+                                });
+                                setTimeout(() => setToast({ show: false, message: '', type: '' }), 3000);
+                            } else if (errors) {
+                                setToast({
+                                    show: true,
+                                    message: `Failed to create tag: ${errors[0]?.message}`,
+                                    type: 'error',
+                                });
+                                setTimeout(() => setToast({ show: false, message: '', type: '' }), 4000);
+                                throw new Error(errors[0].message);
+                            }
+                        },
+                    });
+
+                    // Refresh the list
+                    tagsRefetch();
+                    return response.data?.createTag;
+                }),
+
+                // Update actor
+                updateTag: fromPromise(async ({ input }) => {
+                    const { tag } = input;
+                    const response = await updateTag({
+                        variables: {
+                            id: tag.id,
+                            request: {
+                                name: tag.name,
+                                description: tag.description,
+                                projectId: tag.project?.id,
+                                tagTypeId: tag.tagType?.id,
+                            },
+                        },
+                    });
+                    tagsRefetch();
+                    return response.data?.updateTag;
+                }),
+
+                // Delete actor
+                deleteTag: fromPromise(async ({ input }) => {
+                    const { id } = input;
+                    await removeTag({
+                        variables: { id },
+                        update: (cache, { data, errors }) => {
+                            if (data) {
+                                setToast({
+                                    show: true,
+                                    message: 'Tag has been deleted!',
+                                    type: 'success',
+                                });
+                                setTimeout(() => setToast({ show: false, message: '', type: '' }), 3000);
+                            }
+                        },
+                    });
+                    return { id };
+                }),
+            },
+        }),
+    );
+
+    const { filteredTags, projects, tagTypes, searchQuery, isLoading } = state.context;
+
+    // Trigger data fetch when GraphQL data is available
+    React.useEffect(() => {
+        if (tagsData && projectsData && tagTypesData) {
+            send({ type: 'FETCH' });
+        }
+    }, [send, tagsData, projectsData, tagTypesData]);
+
+    // Component render
+    return (
+        <div className="min-h-screen bg-background">
+            {/* Toast notifications */}
+            {toast.show && (
+                <div
+                    className={`fixed top-4 right-4 px-4 py-2 rounded-themed shadow-themed-lg z-50 
+                    ${
+                        toast.type === 'success'
+                            ? 'bg-success text-success-foreground'
+                            : 'bg-destructive text-destructive-foreground'
+                    }`}
+                >
+                    <span>{toast.message}</span>
+                </div>
+            )}
+
+            {/* Header */}
+            <div className="flex justify-between items-center mb-6">
+                <h1 className="text-2xl font-bold text-foreground">Tags</h1>
+                <button onClick={() => send({ type: 'OPEN_CREATE_MODAL' })} className="themed-button focus-themed">
+                    Create Tag
+                </button>
+            </div>
+
+            {/* Search */}
+            <input
+                type="text"
+                placeholder="Search tags..."
+                value={searchQuery}
+                onChange={(e) => send({ type: 'SEARCH', query: e.target.value })}
+                className="themed-input w-full mb-4 focus-themed"
+            />
+
+            {/* Tags list */}
+            {isLoading ? (
+                <div>Loading...</div>
+            ) : (
+                <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+                    {filteredTags.map((tag) => (
+                        <div key={tag.id} className="themed-card p-4">
+                            <h3 className="font-semibold">{tag.name}</h3>
+                            <p className="text-sm text-muted-foreground">{tag.description}</p>
+                        </div>
+                    ))}
+                </div>
+            )}
+
+            {/* Modal Form */}
+            <TagModal
+                isOpen={state.context.isCreateModalOpen || state.context.isEditModalOpen}
+                onClose={() => send({ type: 'CLOSE_CREATE_MODAL' })}
+                title={state.context.isEditModalOpen ? 'Edit Tag' : 'Create Tag'}
+                draftTag={state.context.draftTag}
+                projects={projects}
+                tagTypes={tagTypes}
+                send={send}
+                onSubmit={(e) => {
+                    e.preventDefault();
+                    if (state.context.isEditModalOpen) {
+                        send({ type: 'UPDATE_TAG' });
+                    } else {
+                        send({ type: 'SUBMIT_TAG' });
+                    }
+                }}
+            />
+        </div>
+    );
+}
+```
+
+---
+
+### **Step 2: XState Machine for Form State Management**
+
+```typescript
+// tagsMachine.ts - State machine with organization context
+import { createMachine, assign } from 'xstate';
+import type { ITagType } from 'common/server';
+
+// 🔑 Type definition with organization field
+export type Tag = {
+    id: string;
+    tagId: string;
+    name: string;
+    description?: string;
+    createdAt: string;
+    updatedAt: string;
+    createdBy: string;
+    orgName: string; // Organization context
+    tagType: {
+        id: string;
+        name: string;
+        color: string;
+    };
+    color: string;
+    project: {
+        id: string;
+        name: string;
+    };
+    organization: {
+        id: string;
+        name: string;
+    };
+};
+
+type TagsContext = {
+    tags: Tag[];
+    projects: Project[];
+    tagTypes: ITagType[];
+    filteredTags: Tag[];
+    searchQuery: string;
+    isLoading: boolean;
+    error: string | null;
+    isCreateModalOpen: boolean;
+    isEditModalOpen: boolean;
+    draftTag: Partial<Tag> | null;
+    validationErrors?: Record<string, string>;
+    tagsLoaded: boolean;
+    projectsLoaded: boolean;
+    tagTypesLoaded: boolean;
+};
+
+type TagsEvent =
+    | { type: 'FETCH' }
+    | { type: 'SEARCH'; query: string }
+    | { type: 'OPEN_CREATE_MODAL' }
+    | { type: 'CLOSE_CREATE_MODAL' }
+    | { type: 'OPEN_EDIT_MODAL'; tag: Tag }
+    | { type: 'UPDATE_DRAFT'; value: Partial<Tag> }
+    | { type: 'SUBMIT_TAG' }
+    | { type: 'UPDATE_TAG' }
+    | { type: 'DELETE_TAG'; id: string };
+
+const defaultDraftTag: Partial<Tag> = {
+    name: '',
+    description: '',
+};
+
+// Helper function for search filtering
+const filterTags = (tags: Tag[], query: string): Tag[] => {
+    if (!query) return tags;
+    const lowercaseQuery = query.toLowerCase();
+    return tags.filter(
+        (tag) =>
+            tag.name.toLowerCase().includes(lowercaseQuery) ||
+            (tag.description?.toLowerCase() || '').includes(lowercaseQuery),
+    );
+};
+
+export const tagsMachine = createMachine({
+    id: 'tags',
+    types: {} as {
+        context: TagsContext;
+        events: TagsEvent;
+    },
+    initial: 'loading',
+    context: {
+        tags: [],
+        projects: [],
+        tagTypes: [],
+        filteredTags: [],
+        searchQuery: '',
+        isLoading: true,
+        error: null,
+        isCreateModalOpen: false,
+        isEditModalOpen: false,
+        draftTag: null,
+        validationErrors: {},
+        tagsLoaded: false,
+        projectsLoaded: false,
+        tagTypesLoaded: false,
+    },
+    states: {
+        loading: {
+            // Parallel invocations for fetching multiple data sources
+            invoke: [
+                {
+                    src: 'fetchTags',
+                    onDone: {
+                        actions: assign({
+                            tags: ({ event }) => event.output,
+                            filteredTags: ({ event }) => event.output,
+                            tagsLoaded: true,
+                        }),
+                    },
+                    onError: {
+                        target: 'error',
+                        actions: assign({
+                            error: ({ event }) => String(event.error),
+                            isLoading: false,
+                        }),
+                    },
+                },
+                {
+                    src: 'fetchProjects',
+                    onDone: {
+                        actions: assign({
+                            projects: ({ event }) => event.output,
+                            projectsLoaded: true,
+                        }),
+                    },
+                },
+                {
+                    src: 'fetchTagTypes',
+                    onDone: {
+                        actions: assign({
+                            tagTypes: ({ event }) => event.output,
+                            tagTypesLoaded: true,
+                        }),
+                    },
+                },
+            ],
+            // Transition to idle when all data is loaded
+            always: {
+                target: 'idle',
+                guard: ({ context }) => context.tagsLoaded && context.projectsLoaded && context.tagTypesLoaded,
+                actions: assign({ isLoading: false }),
+            },
+        },
+        idle: {
+            on: {
+                FETCH: {
+                    target: 'loading',
+                    actions: assign({
+                        isLoading: true,
+                        tagsLoaded: false,
+                        projectsLoaded: false,
+                        tagTypesLoaded: false,
+                    }),
+                },
+                SEARCH: {
+                    actions: assign({
+                        searchQuery: ({ event }) => event.query || '',
+                        filteredTags: ({ context, event }) => filterTags(context.tags, event.query),
+                    }),
+                },
+                OPEN_CREATE_MODAL: {
+                    actions: assign({
+                        isCreateModalOpen: true,
+                        draftTag: () => ({ ...defaultDraftTag }),
+                    }),
+                },
+                CLOSE_CREATE_MODAL: {
+                    actions: assign({
+                        isCreateModalOpen: false,
+                        isEditModalOpen: false,
+                        draftTag: null,
+                    }),
+                },
+                OPEN_EDIT_MODAL: {
+                    actions: assign({
+                        isEditModalOpen: true,
+                        draftTag: ({ event }) => ({ ...event.tag }),
+                    }),
+                },
+                UPDATE_DRAFT: {
+                    actions: assign({
+                        draftTag: ({ context, event }) => ({
+                            ...context.draftTag,
+                            ...event.value,
+                        }),
+                    }),
+                },
+                SUBMIT_TAG: {
+                    target: 'submitting',
+                    guard: ({ context }) => Boolean(context.draftTag?.name),
+                },
+                UPDATE_TAG: {
+                    target: 'updating',
+                },
+                DELETE_TAG: {
+                    target: 'deleting',
+                },
+            },
+        },
+        submitting: {
+            invoke: {
+                src: 'submitTag',
+                input: ({ context }) => ({ tag: context.draftTag! }),
+                onDone: {
+                    target: 'idle',
+                    actions: assign({
+                        tags: ({ context, event }) => [...context.tags, event.output],
+                        filteredTags: ({ context, event }) => {
+                            const updatedTags = [...context.tags, event.output];
+                            return filterTags(updatedTags, context.searchQuery);
+                        },
+                        isCreateModalOpen: false,
+                        draftTag: null,
+                    }),
+                },
+                onError: {
+                    target: 'idle',
+                    actions: assign({
+                        error: ({ event }) => String(event.error),
+                    }),
+                },
+            },
+        },
+        updating: {
+            invoke: {
+                src: 'updateTag',
+                input: ({ context }) => ({ tag: context.draftTag! }),
+                onDone: {
+                    target: 'idle',
+                    actions: assign({
+                        tags: ({ context, event }) =>
+                            context.tags.map((tag) => (tag.id === event.output.id ? event.output : tag)),
+                        filteredTags: ({ context, event }) => {
+                            const updatedTags = context.tags.map((tag) =>
+                                tag.id === event.output.id ? event.output : tag,
+                            );
+                            return filterTags(updatedTags, context.searchQuery);
+                        },
+                        isEditModalOpen: false,
+                        draftTag: null,
+                    }),
+                },
+                onError: {
+                    target: 'idle',
+                    actions: assign({
+                        error: ({ event }) => String(event.error),
+                    }),
+                },
+            },
+        },
+        deleting: {
+            invoke: {
+                src: 'deleteTag',
+                input: ({ event }) => ({ id: (event as any).id }),
+                onDone: {
+                    target: 'idle',
+                    actions: assign({
+                        tags: ({ context, event }) => context.tags.filter((tag) => tag.id !== event.output.id),
+                        filteredTags: ({ context, event }) => {
+                            const updatedTags = context.tags.filter((tag) => tag.id !== event.output.id);
+                            return filterTags(updatedTags, context.searchQuery);
+                        },
+                    }),
+                },
+            },
+        },
+        error: {
+            on: {
+                FETCH: 'loading',
+            },
+        },
+    },
+});
+```
+
+---
+
+### **Step 3: Modal Form Component**
+
+```tsx
+// TagModal.tsx - Reusable form modal component
+import React from 'react';
+import type { ITagType } from 'common/server';
+
+interface TagModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    title: string;
+    draftTag: any;
+    projects: any[];
+    tagTypes: ITagType[];
+    send: any;
+    onSubmit: (e: React.FormEvent) => void;
+}
+
+// 🔑 Extract modal outside parent to prevent re-renders
+const TagModal: React.FC<TagModalProps> = ({
+    isOpen,
+    onClose,
+    title,
+    draftTag,
+    projects,
+    tagTypes,
+    send,
+    onSubmit,
+}) => {
+    if (!isOpen || !draftTag) return null;
+
+    return (
+        <div className="fixed inset-0 z-10 overflow-y-auto">
+            <div className="flex items-end justify-center min-h-screen pt-4 px-4 pb-20 text-center sm:block sm:p-0">
+                {/* Backdrop */}
+                <div
+                    className="fixed inset-0 bg-black/50 backdrop-blur-sm transition-opacity"
+                    onClick={onClose}
+                    aria-hidden="true"
+                />
+
+                {/* Center modal */}
+                <span className="hidden sm:inline-block sm:align-middle sm:h-screen" aria-hidden="true">
+                    &#8203;
+                </span>
+
+                {/* Modal panel */}
+                <div className="themed-card inline-block align-bottom rounded-themed-lg px-4 pt-5 pb-4 text-left overflow-hidden shadow-themed-xl transform transition-all sm:my-8 sm:align-middle sm:max-w-lg sm:w-full sm:p-6">
+                    <div className="sm:flex sm:items-start">
+                        <div className="mt-3 text-center sm:mt-0 sm:text-left w-full">
+                            <h3 className="text-lg leading-6 font-medium text-foreground">{title}</h3>
+
+                            <form onSubmit={onSubmit} className="mt-6 space-y-4">
+                                {/* Name Field */}
+                                <div>
+                                    <label htmlFor="name" className="block text-sm font-medium text-foreground">
+                                        Name <span className="text-destructive">*</span>
+                                    </label>
+                                    <input
+                                        type="text"
+                                        id="name"
+                                        value={draftTag.name || ''}
+                                        onChange={(e) =>
+                                            send({
+                                                type: 'UPDATE_DRAFT',
+                                                value: { name: e.target.value },
+                                            })
+                                        }
+                                        className="themed-input mt-1 block w-full rounded-themed focus-themed"
+                                        required
+                                        autoFocus
+                                        aria-required="true"
+                                    />
+                                </div>
+
+                                {/* Project Selection */}
+                                <div>
+                                    <label htmlFor="project" className="block text-sm font-medium text-foreground">
+                                        Project <span className="text-destructive">*</span>
+                                    </label>
+                                    <select
+                                        id="project"
+                                        value={draftTag.project?.id || ''}
+                                        required
+                                        onChange={(e) => {
+                                            const selectedProject = projects.find((p) => p.id === e.target.value);
+                                            send({
+                                                type: 'UPDATE_DRAFT',
+                                                value: {
+                                                    project: selectedProject
+                                                        ? {
+                                                              id: selectedProject.id,
+                                                              name: selectedProject.name,
+                                                          }
+                                                        : null,
+                                                },
+                                            });
+                                        }}
+                                        className="themed-input mt-1 block w-full rounded-themed focus-themed"
+                                        aria-required="true"
+                                    >
+                                        <option value="">Select a project</option>
+                                        {projects.map((project) => (
+                                            <option key={project.id} value={project.id}>
+                                                {project.name}
+                                            </option>
+                                        ))}
+                                    </select>
+                                </div>
+
+                                {/* Tag Type Selection */}
+                                <div>
+                                    <label htmlFor="tagType" className="block text-sm font-medium text-foreground">
+                                        Tag Type <span className="text-destructive">*</span>
+                                    </label>
+                                    <select
+                                        id="tagType"
+                                        value={draftTag.tagType?.id || ''}
+                                        onChange={(e) => {
+                                            const selectedTagType = tagTypes.find((tt) => tt.id === e.target.value);
+                                            send({
+                                                type: 'UPDATE_DRAFT',
+                                                value: {
+                                                    tagType: selectedTagType
+                                                        ? {
+                                                              id: selectedTagType.id,
+                                                              name: selectedTagType.name,
+                                                              color: selectedTagType.color,
+                                                          }
+                                                        : null,
+                                                },
+                                            });
+                                        }}
+                                        className="themed-input mt-1 block w-full rounded-themed focus-themed"
+                                        required
+                                        aria-required="true"
+                                    >
+                                        <option value="">Select a tag type</option>
+                                        {tagTypes.map((tagType) => (
+                                            <option key={tagType.id} value={tagType.id}>
+                                                {tagType.name}
+                                            </option>
+                                        ))}
+                                    </select>
+                                </div>
+
+                                {/* Description Field */}
+                                <div>
+                                    <label htmlFor="description" className="block text-sm font-medium text-foreground">
+                                        Description <span className="text-muted-foreground">(Optional)</span>
+                                    </label>
+                                    <textarea
+                                        id="description"
+                                        value={draftTag.description || ''}
+                                        onChange={(e) =>
+                                            send({
+                                                type: 'UPDATE_DRAFT',
+                                                value: { description: e.target.value },
+                                            })
+                                        }
+                                        rows={3}
+                                        className="themed-input mt-1 block w-full rounded-themed focus-themed"
+                                        placeholder="Enter a description for this tag..."
+                                    />
+                                </div>
+
+                                {/* Action Buttons */}
+                                <div className="mt-5 sm:mt-4 sm:flex sm:flex-row-reverse">
+                                    <button
+                                        type="submit"
+                                        className="themed-button w-full sm:ml-3 sm:w-auto focus-themed"
+                                    >
+                                        {draftTag.id ? 'Update Tag' : 'Create Tag'}
+                                    </button>
+                                    <button
+                                        type="button"
+                                        onClick={onClose}
+                                        className="bg-secondary text-secondary-foreground w-full sm:w-auto mt-3 sm:mt-0 px-4 py-2 rounded-themed hover:bg-secondary/80 transition-colors focus-themed"
+                                    >
+                                        Cancel
+                                    </button>
+                                </div>
+                            </form>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </div>
+    );
+};
+
+export default TagModal;
+```
+
+---
+
+### **Step 4: GraphQL Query Patterns**
+
+```typescript
+// Queries with organization context
+const { data, loading, error } = useGetTagsQuery({
+    variables: { orgName }, // ✅ Pass organization context
+    errorPolicy: 'all', // ✅ Handle partial data gracefully
+});
+
+// Mutations - organization context from backend @addAccountContext
+const [createTag] = useCreateTagMutation();
+const response = await createTag({
+    variables: {
+        request: {
+            projectId: tag.project.id,
+            tagTypeId: tag.tagType.id,
+            name: tag.name,
+            description: tag.description,
+        },
+        // ✅ NO orgName/orgId needed - backend gets it from userContext
+    },
+    // ✅ Cache update after mutation
+    update: (cache, { data, errors }) => {
+        if (data?.createTag) {
+            // Optimistically update cache
+            cache.modify({
+                fields: {
+                    getTags(existingTags = { data: [] }) {
+                        return {
+                            ...existingTags,
+                            data: [...existingTags.data, data.createTag],
+                        };
+                    },
+                },
+            });
+        }
+    },
+});
+```
+
+---
+
+## 🎯 Frontend Implementation Checklist
+
+### **React Component Setup**
+
+- [ ] Extract `orgName` from `useParams<{ orgName: string }>()`
+- [ ] Pass `orgName` to all GraphQL queries requiring organization context
+- [ ] Use `errorPolicy: 'all'` for partial data handling
+- [ ] Implement loading and error states
+- [ ] Add toast notifications for user feedback
+- [ ] Import hooks from `common/graphql` (not local files)
+
+### **XState Machine**
+
+- [ ] Define comprehensive context type with all form fields
+- [ ] Include organization-related fields in entity types
+- [ ] Create states: `loading`, `idle`, `submitting`, `updating`, `deleting`, `error`
+- [ ] Implement proper state transitions with guards
+- [ ] Use `fromPromise` for async operations (fetch/submit/update/delete actors)
+- [ ] Handle validation in guards or actors
+- [ ] Use `assign` for context updates
+- [ ] Implement search/filter logic in event handlers
+
+### **Form Modal**
+
+- [ ] Extract modal component outside parent to prevent re-renders
+- [ ] Implement controlled inputs with XState `send` function
+- [ ] Add proper validation with error messages
+- [ ] Use `send({ type: 'UPDATE_DRAFT', value })` for field updates
+- [ ] Handle form submission with `send({ type: 'SUBMIT_TAG' })`
+- [ ] Add cancel/close functionality
+- [ ] Add accessibility attributes (`aria-required`, `aria-label`)
+- [ ] Auto-focus first input field
+- [ ] Show loading state on submit button
+
+### **GraphQL Integration**
+
+- [ ] Import generated hooks from `common/graphql`
+- [ ] Pass organization variables (`orgName`) to queries
+- [ ] Handle mutation responses with optimistic updates
+- [ ] Implement cache updates after mutations using `update` callback
+- [ ] Refetch queries after successful mutations if needed
+- [ ] Use `errorPolicy: 'all'` to handle partial data
+- [ ] Filter out null/invalid entries from response data
+
+### **Error Handling**
+
+- [ ] Use `errorPolicy: 'all'` for queries
+- [ ] Filter null/invalid data entries with `.filter(item => item && item.id)`
+- [ ] Display partial data warnings to users
+- [ ] Show user-friendly error messages in toast notifications
+- [ ] Log detailed errors to console for debugging
+- [ ] Handle network errors gracefully
+- [ ] Validate required fields before submission
+
+### **User Experience**
+
+- [ ] Add loading spinners during data fetch
+- [ ] Show toast notifications for success/error/info
+- [ ] Auto-hide toasts after 3-4 seconds
+- [ ] Disable system/default entities from editing/deletion
+- [ ] Validate required fields before submission
+- [ ] Show validation errors inline
+- [ ] Add empty state messages when no data
+- [ ] Implement search/filter functionality
+- [ ] Add keyboard shortcuts (Escape to close modal)
+- [ ] Make modals responsive for mobile
+
+---
+
+## 🚨 Common Frontend Mistakes
+
+### ❌ Mistake 1: Missing Organization Context in Queries
+
+```tsx
+// ❌ WRONG - No organization context
+const { data } = useGetTagsQuery();
+
+// Result: Query returns data for wrong organization or fails
+```
+
+```tsx
+// ✅ CORRECT - Organization from route params
+const { orgName } = useParams<{ orgName: string }>();
+const { data } = useGetTagsQuery({
+    variables: { orgName },
+});
+```
+
+**Why**: Backend uses `@addAccountContext` directive which requires `orgName` to resolve organization context.
+
+---
+
+### ❌ Mistake 2: Not Handling Partial Data
+
+```tsx
+// ❌ WRONG - Will crash on partial errors
+const tags = data.getTags.data;
+tags.map((tag) => <div>{tag.name}</div>);
+
+// Result: TypeError: Cannot read property 'data' of undefined
+```
+
+```tsx
+// ✅ CORRECT - Filter null entries and handle errors
+const tags = (data?.getTags?.data || []).filter((tag) => tag && tag.id);
+tags.map((tag) => <div>{tag.name}</div>);
+```
+
+**Why**: GraphQL can return partial data when some fields fail. Always use optional chaining and filter invalid entries.
+
+---
+
+### ❌ Mistake 3: Creating Modal Inside Parent Component
+
+```tsx
+// ❌ WRONG - Modal recreated on every render
+export function TagsView() {
+    const TagModal = () => {
+        return <div>Modal content</div>;
+    };
+
+    return (
+        <div>
+            <TagModal />
+        </div>
+    );
+}
+
+// Result: Performance issues, state loss on re-render
+```
+
+```tsx
+// ✅ CORRECT - Modal outside parent component
+const TagModal = (props) => {
+    return <div>Modal content</div>;
+};
+
+export function TagsView() {
+    return (
+        <div>
+            <TagModal {...props} />
+        </div>
+    );
+}
+```
+
+**Why**: Defining components inside other components causes them to remount on every render, losing internal state.
+
+---
+
+### ❌ Mistake 4: Not Refetching After Mutations
+
+```tsx
+// ❌ WRONG - Stale data after mutation
+await createTag({ variables: { request } });
+// List not updated!
+
+// Result: User doesn't see new item until page refresh
+```
+
+```tsx
+// ✅ CORRECT - Refetch or update cache
+await createTag({
+    variables: { request },
+    update: (cache, { data }) => {
+        // Update Apollo cache
+        cache.modify({
+            fields: {
+                getTags(existing) {
+                    return {
+                        ...existing,
+                        data: [...existing.data, data.createTag],
+                    };
+                },
+            },
+        });
+    },
+});
+
+// OR simply refetch
+tagsRefetch();
+```
+
+**Why**: Apollo cache doesn't automatically update after mutations. Must manually update or refetch.
+
+---
+
+### ❌ Mistake 5: Missing Error Policy
+
+```tsx
+// ❌ WRONG - Entire query fails on any error
+const { data } = useGetTagsQuery({
+    variables: { orgName },
+});
+
+// Result: No data shown even if some tags loaded successfully
+```
+
+```tsx
+// ✅ CORRECT - Allow partial data with errors
+const { data, error } = useGetTagsQuery({
+    variables: { orgName },
+    errorPolicy: 'all', // Return partial data even with errors
+});
+
+if (error) {
+    console.error('Partial error:', error);
+    // Still render available data
+}
+```
+
+**Why**: Some queries may fail partially (e.g., organization field resolution fails for one item). `errorPolicy: 'all'` allows rendering valid data.
+
+---
+
+### ❌ Mistake 6: Not Passing orgId in Mutations
+
+```tsx
+// ❌ WRONG - Passing orgId/orgName in mutation
+await createTag({
+    variables: {
+        request: {
+            organizationId: orgId, // ❌ Not needed!
+            name: tag.name,
+        },
+    },
+});
+
+// Result: Backend ignores this - gets orgId from userContext anyway
+```
+
+```tsx
+// ✅ CORRECT - No organization in mutation variables
+await createTag({
+    variables: {
+        request: {
+            // ✅ Backend gets orgId from @addAccountContext directive
+            name: tag.name,
+            projectId: tag.project.id,
+        },
+    },
+});
+```
+
+**Why**: Backend `@addAccountContext` directive automatically injects organization context into `userContext`. Service layer uses `userContext.orgId`.
+
+---
+
+### ❌ Mistake 7: Not Validating Before Submission
+
+```tsx
+// ❌ WRONG - No validation
+const submitTag = async () => {
+    await createTag({ variables: { request: draftTag } });
+};
+
+// Result: Backend errors, poor UX
+```
+
+```tsx
+// ✅ CORRECT - Validate in actor or guard
+submitTag: fromPromise(async ({ input }) => {
+    const { tag } = input;
+
+    // Client-side validation
+    if (!tag.name?.trim()) {
+        throw new Error('Name is required');
+    }
+
+    if (!tag.project?.id) {
+        throw new Error('Project must be selected');
+    }
+
+    return await createTag({ variables: { request: tag } });
+}),
+
+// In machine
+SUBMIT_TAG: {
+    target: 'submitting',
+    guard: ({ context }) => {
+        // Guard prevents transition if validation fails
+        return Boolean(context.draftTag?.name?.trim());
+    },
+},
+```
+
+**Why**: Client-side validation provides immediate feedback and prevents unnecessary network requests.
+
+---
+
+### ❌ Mistake 8: Importing from Local Instead of common/graphql
+
+```tsx
+// ❌ WRONG - Local import
+import { useGetTagsQuery } from './queries/generated';
+
+// Result: May work but defeats code generation purpose
+```
+
+```tsx
+// ✅ CORRECT - Import from common/graphql
+import { useGetTagsQuery } from 'common/graphql';
+```
+
+**Why**: Code generation creates centralized types/hooks in `common/graphql` for consistency across all packages.
+
+---
+
+## 📊 Complete Data Flow: Frontend to Backend
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│                    Frontend → Backend Flow                      │
+└────────────────────────────────────────────────────────────────┘
+
+1. USER NAVIGATES TO ROUTE
+   URL: /org/acme-corp/projects/tags
+   Route: <Route path="/:orgName/projects/tags" />
+
+2. REACT COMPONENT MOUNTS
+   const { orgName } = useParams(); // "acme-corp"
+
+3. GRAPHQL QUERY EXECUTED
+   useGetTagsQuery({
+     variables: { orgName: "acme-corp" }
+   })
+   ↓
+   Apollo Client sends to GraphQL server
+
+4. BACKEND RECEIVES QUERY
+   Query getTags(orgName: "acme-corp")
+   ↓
+   @addAccountContext directive intercepts
+   ↓
+   Resolves: orgName → orgId via OrganizationService.getBySlug()
+   ↓
+   Injects userContext.orgId = "507f1f77bcf86cd799439011"
+
+5. RESOLVER LAYER
+   getTags: (_, args, { tagService, userContext }) =>
+     tagService.getTags(userContext.orgId, args.projectId, ...)
+   ↓
+   Resolver uses userContext.orgId (NOT args.orgName)
+
+6. SERVICE LAYER
+   getTags(orgId: string, projectId?: string, ...) {
+     // orgId already resolved - no slug service needed
+     const match = {
+       organization: new mongoose.Types.ObjectId(orgId),
+       ...(projectId && { project: new mongoose.Types.ObjectId(projectId) })
+     };
+     return tagRepository.getAll({ criteria: match });
+   }
+
+7. REPOSITORY LAYER
+   getAll(criteria: { organization: ObjectId }) {
+     return TagModel.find(criteria)
+       .populate('organization')
+       .populate('project')
+       .populate('tagType');
+   }
+
+8. DATABASE QUERY
+   db.tags.find({
+     organization: ObjectId("507f1f77bcf86cd799439011")
+   })
+
+9. RESPONSE TO FRONTEND
+   {
+     getTags: {
+       totalCount: 5,
+       data: [
+         {
+           id: "tag1",
+           name: "Bug",
+           organization: {
+             id: "507f1f77bcf86cd799439011",
+             name: "ACME Corp"
+           },
+           project: { id: "proj1", name: "Project A" },
+           tagType: { id: "type1", name: "Bug", color: "#ff0000" }
+         },
+         // ... more tags
+       ]
+     }
+   }
+
+10. FRONTEND STATE UPDATE
+    XState machine:
+    - fetchTags actor receives response
+    - Filters null entries: .filter(tag => tag && tag.id)
+    - Updates context: assign({ tags: validTags })
+    ↓
+    React re-renders with new data
+    ↓
+    UI displays tag list
+
+11. USER CREATES TAG
+    Form submission → send({ type: 'SUBMIT_TAG' })
+    ↓
+    Machine transitions to 'submitting' state
+    ↓
+    submitTag actor invoked:
+
+    useCreateTagMutation({
+      variables: {
+        request: {
+          projectId: "proj1",
+          tagTypeId: "type1",
+          name: "New Bug Tag"
+        }
+      }
+    })
+    ↓
+    Backend @addAccountContext gets orgId from request headers
+    ↓
+    Service creates tag with organization ObjectId
+    ↓
+    Response with new tag
+    ↓
+    Apollo cache updated via 'update' callback
+    ↓
+    Query refetched: tagsRefetch()
+    ↓
+    Machine transitions to 'idle'
+    ↓
+    UI shows success toast
+    ↓
+    Modal closes
+```
+
+---
+
+## 🎨 Styling Best Practices
+
+### **Use Themed Classes**
+
+The AdminIDE stack uses theme-aware CSS classes that adapt to light/dark modes:
+
+```tsx
+// Input fields
+<input className="themed-input focus-themed" />
+
+// Buttons
+<button className="themed-button focus-themed">Submit</button>
+
+// Cards/Panels
+<div className="themed-card shadow-themed-lg" />
+
+// Success/Error states
+<div className="bg-success text-success-foreground">Success!</div>
+<div className="bg-destructive text-destructive-foreground">Error!</div>
+
+// Text colors
+<p className="text-foreground">Primary text</p>
+<p className="text-muted-foreground">Secondary text</p>
+
+// Background colors
+<div className="bg-background">Main background</div>
+<div className="bg-card">Card background</div>
+```
+
+### **Responsive Design**
+
+```tsx
+// Mobile-first approach
+<div className="flex flex-col sm:flex-row">
+    <button className="w-full sm:w-auto sm:ml-3">Submit</button>
+</div>
+
+// Grid layouts
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+    {items.map(item => <Card key={item.id} />)}
+</div>
+
+// Responsive padding
+<div className="px-4 sm:px-6 lg:px-8">
+    Content
+</div>
+```
+
+### **Accessibility**
+
+```tsx
+// Labels and inputs
+<label htmlFor="name" className="block text-sm font-medium">
+    Name <span className="text-destructive">*</span>
+</label>
+<input
+    id="name"
+    aria-required="true"
+    aria-invalid={!!errors.name}
+    aria-describedby={errors.name ? "name-error" : undefined}
+    autoFocus
+/>
+{errors.name && (
+    <p id="name-error" className="text-destructive text-sm mt-1">
+        {errors.name}
+    </p>
+)}
+
+// Buttons
+<button
+    aria-label="Close modal"
+    onClick={onClose}
+>
+    <XIcon aria-hidden="true" />
+</button>
+
+// Loading states
+<button disabled={isLoading} aria-busy={isLoading}>
+    {isLoading ? 'Saving...' : 'Save'}
+</button>
+```
+
+---
+
+## 🧪 Testing Checklist
+
+### **Query Testing**
+
+- [ ] Test with valid organization context (`orgName` in params)
+- [ ] Test without organization context (should error or redirect)
+- [ ] Test partial data scenarios (some items fail to load)
+- [ ] Test network errors (offline, timeout)
+- [ ] Test empty results (no tags for organization)
+- [ ] Test filtering/search with various inputs
+- [ ] Test loading states displayed correctly
+
+### **Mutation Testing**
+
+- [ ] Test successful creation with valid data
+- [ ] Test successful update with changed fields
+- [ ] Test successful deletion
+- [ ] Test validation errors (missing required fields)
+- [ ] Test backend errors (duplicate names, constraints)
+- [ ] Test network errors during submission
+- [ ] Test cache updates after mutations
+- [ ] Test refetch after mutations
+
+### **State Machine Testing**
+
+- [ ] Test all state transitions (loading → idle → submitting → idle)
+- [ ] Test event handlers (FETCH, SEARCH, SUBMIT_TAG, etc.)
+- [ ] Test guards (SUBMIT_TAG blocked if name empty)
+- [ ] Test context updates (assign actions work correctly)
+- [ ] Test error states and recovery
+- [ ] Test parallel invocations (fetchTags, fetchProjects, fetchTagTypes)
+
+### **UI/UX Testing**
+
+- [ ] Test toast notifications appear and disappear
+- [ ] Test modal open/close animations
+- [ ] Test form field updates reflect in state
+- [ ] Test keyboard navigation (Tab, Enter, Escape)
+- [ ] Test responsive layout on mobile/tablet/desktop
+- [ ] Test accessibility with screen reader
+- [ ] Test dark/light theme switching
+
+### **Integration Testing**
+
+- [ ] Test complete flow: load → create → update → delete
+- [ ] Test with multiple browser tabs (concurrent edits)
+- [ ] Test with slow network (loading states)
+- [ ] Test with backend errors (500, 404, validation)
+- [ ] Test authentication errors (token expired)
+- [ ] Test permission errors (unauthorized actions)
+
+---
+
+## 📚 Key Takeaways
+
+1. ✅ **Always extract `orgName` from route params** - Required for organization-scoped queries
+2. ✅ **Pass `orgName` to all organization-scoped queries** - Backend needs it for context resolution
+3. ✅ **Backend handles organization resolution via `@addAccountContext`** - Don't pass orgId in mutations
+4. ✅ **Use XState for complex form workflows** - Better state management than useState
+5. ✅ **Handle partial data with `errorPolicy: 'all'`** - Gracefully handle field resolution errors
+6. ✅ **Update cache or refetch after mutations** - Keep UI in sync with backend
+7. ✅ **Provide user feedback with toast notifications** - Confirm actions and show errors
+8. ✅ **Extract modals to prevent unnecessary re-renders** - Define outside parent component
+9. ✅ **Validate data before submission** - Better UX and fewer backend errors
+10. ✅ **Filter null/invalid entries from GraphQL responses** - Prevent runtime errors
+
+---
+
+## 🔗 Related Documentation
+
+- [Backend Service Creation Template](./LLM-Service-Creation-Template.md) - Backend patterns
+- [XState Documentation](https://xstate.js.org/docs/) - State machine patterns
+- [Apollo Client Documentation](https://www.apollographql.com/docs/react/) - GraphQL client
+- [Remix Documentation](https://remix.run/docs) - React framework
+- [TailwindCSS Documentation](https://tailwindcss.com/docs) - Utility-first CSS
+
+---
+
+## 📝 Example: Complete Tag Form Implementation
+
+See the following files for a complete working example:
+
+- `packages/client-organization/app/routes/$orgName.projects.tags.tsx` - Main view component
+- `packages/client-organization/app/machines/tagsMachine.ts` - XState machine
+- `packages/common/graphql/src/generated.ts` - Generated GraphQL hooks
+
+---
+
+**This frontend pattern ensures consistent organization context throughout the application and provides a smooth user experience!** 🚀