Skip to content

AI_CONSTRAINTS.md

Latest commit

 

History

History
249 lines (204 loc) · 8.19 KB

AI_CONSTRAINTS.md

File metadata and controls

249 lines (204 loc) · 8.19 KB

Vibe Platform - AI Constraints & LLM Documentation

🎯 AI File Creation Guidelines (Frontend-Enforced)

Recommended AI Actions

The AI (via OpenRouter) should only create/modify files in:

  • src/ directory - All application source code
  • package.json - For npm package management and dependencies

Recommended Restrictions

The frontend should prevent AI from creating/modifying:

  • System configuration files (vite.config.ts, tsconfig.json, etc.)
  • Build scripts and tooling
  • Docker-related files
  • ESLint, PostCSS, or Tailwind configurations
  • HTML files
  • Any files outside the src/ directory (except package.json)

Note: Backend has no restrictions - all validation occurs on frontend

🏗️ System Architecture

Auto-Generated System Files

All system files are automatically copied from the React base template:

/react-base/
├── vite.config.ts          # Vite configuration
├── tsconfig.json           # TypeScript config
├── tsconfig.app.json       # App-specific TypeScript config
├── tsconfig.node.json      # Node.js TypeScript config
├── eslint.config.js         # ESLint configuration
├── index.html              # HTML template
├── postcss.config.cjs      # PostCSS configuration (auto-generated)
├── tailwind.config.cjs     # Tailwind configuration (auto-generated)
└── Dockerfile              # Container definition

AI-Managed Files (Frontend-Validated)

/project-container/
├── src/                    # Frontend should limit AI to this directory
│   ├── App.tsx
│   ├── main.tsx
│   ├── components/
│   ├── hooks/
│   ├── utils/
│   └── ...                 # Any src/ structure AI desires
└── package.json            # Frontend should allow AI to modify for dependencies

Backend Behavior

The orchestrator backend:

  • Accepts any file operations - no path restrictions
  • Relies on frontend for AI access validation
  • Full container access - can write any file location

🔄 Updated API Behavior

Container Creation Process

  1. System Setup: Copy all system files from React base template
  2. AI Content: Write AI-generated files to src/ directory only
  3. Package Management: Update package.json if AI provides new dependencies
  4. Dependency Installation: Auto-run npm install on package.json changes
  5. Start Services: Launch development server with configured tooling

File Validation

The orchestrator now validates all AI file operations:

const allowedPaths = ['src/', 'package.json'];
const isValidPath = allowedPaths.some(allowedPath => 
  filepath === allowedPath || filepath.startsWith(allowedPath)
);

📡 Updated API Endpoints

Create Container (Modified)

POST /containers
Content-Type: application/json

Request Body (AI-Restricted):

{
  "projectId": "my-project",
  "files": {
    "src/App.tsx": "export default function App() { return <div>Hello World</div>; }",
    "src/components/Button.tsx": "export const Button = () => <button>Click me</button>;",
    "package.json": "{ \"name\": \"my-app\", \"dependencies\": { \"react\": \"^18.0.0\", \"axios\": \"^1.0.0\" } }"
  }
}

System Response: Auto-generated system files + AI files

Update Files (Restricted)

PUT /containers/:containerId/files
Content-Type: application/json

Allowed Updates Only:

{
  "files": {
    "src/App.tsx": "export default function App() { return <div>Updated</div>; }",
    "src/utils/api.ts": "export const api = () => {};",
    "package.json": "{ \"name\": \"my-app\", \"dependencies\": { \"react\": \"^18.0.0\", \"axios\": \"^1.2.0\" } }"
  }
}

🛡️ Security & Safety Features

Path Validation

  • Strict Whitelisting: Only src/ and package.json are allowed
  • Path Traversal Prevention: ../ and absolute paths are blocked
  • Automatic Logging: All unauthorized access attempts are logged

System Integrity

  • Immutable System Files: Configuration files cannot be modified by AI
  • Consistent Build Environment: All containers use identical system configuration
  • Dependency Safety: Package.json updates trigger fresh npm install

🎭 Frontend Integration Guidelines

For LLM Integration

When your frontend interacts with the AI system:

  1. File Path Restrictions: Ensure AI responses only reference src/ paths
  2. Package Management: Handle dependency updates through package.json only
  3. Error Handling: Expect warnings for unauthorized file access attempts
  4. System Files: Never request AI to modify configuration files

AI Prompt Engineering

Recommended constraints for AI prompts:

"Create React components in the src/ directory only. 
You may update package.json to add new dependencies. 
Do not create or modify any configuration files or files outside src/."

Frontend File Validation

// Client-side validation before sending to API
const validateAIFiles = (files) => {
  const allowedPaths = ['src/', 'package.json'];
  const validFiles = {};
  
  for (const [path, content] of Object.entries(files)) {
    const isValid = allowedPaths.some(allowed => 
      path === allowed || path.startsWith(allowed)
    );
    
    if (isValid) {
      validFiles[path] = content;
    } else {
      console.warn(`Invalid path skipped: ${path}`);
    }
  }
  
  return validFiles;
};

🔧 System File Auto-Generation

Template Processing

When creating new containers, the system:

  1. Copies Template Files: All configuration files from React base
  2. Handles ES Modules: Automatic conversion of config files to .cjs if needed
  3. Creates Default Configs: Generates PostCSS and Tailwind configs if missing
  4. Validates Structure: Ensures all required system files exist

Configuration Management

  • Vite: Optimized for development with HMR
  • TypeScript: Strict type checking enabled
  • ESLint: Code quality rules enforced
  • Tailwind CSS: Utility-first styling framework
  • PostCSS: CSS processing pipeline

📊 Monitoring & Logging

AI Behavior Tracking

The system logs all AI file operations:

Writing: src/App.tsx
Writing: src/components/Button.tsx
⚠️  AI attempted to write to restricted path: vite.config.ts (skipping)
Writing: package.json
Installing new dependencies...
✅ Project initialized! 3 files written.

Health Monitoring

System health checks include:

  • File integrity validation
  • Dependency installation status
  • Configuration file consistency
  • Container resource utilization

🚦 Development Workflow

For Frontend Developers

  1. File Management: Only create/modify files in src/ directory
  2. Dependencies: Update package.json for new packages
  3. Build System: Use Vite's built-in tooling (no configuration needed)
  4. Styling: Tailwind CSS is pre-configured and ready to use

For AI Integration

  1. Source Code: All application logic goes in src/
  2. Components: React components in src/components/
  3. Utilities: Helper functions in src/utils/
  4. Hooks: Custom React hooks in src/hooks/
  5. Assets: Images, fonts, etc. in src/assets/

🎯 Best Practices

AI Safety

  • Never request AI to modify system files
  • Always validate AI-generated file paths
  • Use package.json for all dependency management
  • Monitor logs for unauthorized access attempts

Frontend Development

  • Follow React best practices in component structure
  • Utilize TypeScript for type safety
  • Leverage Tailwind CSS for styling
  • Organize code within src/ directory structure

🔄 API Migration Notes

Changes from Previous Version

  • Restricted File Access: AI can only modify src/ and package.json
  • Auto-Generated System Files: All configuration files are now immutable
  • Enhanced Security: Path validation and logging for all operations
  • Simplified Workflow: No need to manage build configuration

Backward Compatibility

  • Existing containers continue to work
  • API endpoints remain the same
  • Only file creation restrictions have been added
  • System file generation is now automatic

Last Updated: January 2024
Platform Version: 1.1.0 - AI Restricted Access