Create ai-assisted-dev

Guide on how to do vibe coding. A walkthrough using Claude AI.
2026-04-25 17:25:21 +02:00 · 2026-01-21 14:36:46 -05:00
parent 2c918627b3
commit 641dd4d2e8
1 changed files with 423 additions and 0 deletions
--- a/docs/ocis/guides/ai-assisted-dev
+++ b/docs/ocis/guides/ai-assisted-dev
@@ -0,0 +1,423 @@
+---
+title: "Building oCIS Web Extensions with AI-Assisted Development"
+date: 2026-01-21T16:00:00+02:00
+weight: 9
+geekdocRepo: https://github.com/owncloud/web-extensions
+geekdocEditPath: edit/master/docs/guides
+geekdocFilePath: ai-assisted-development.md
+geekdocCollapseSection: true
+---
+
+{{< toc >}}
+
+## Introduction
+
+This guide demonstrates how to build oCIS web extensions using AI-assisted development (sometimes called "vibe coding") with Claude AI. By following this approach, you can create production-ready extensions without writing code manually—the AI handles syntax, boilerplate, and implementation while you focus on architecture and user experience.
+
+**What you'll learn:**
+- Setting up MCP connectors so Claude can access your server
+- Using Claude to install development tools and manage your environment
+- The five-phase workflow for AI-assisted extension development
+- Practical tips for supervising AI-generated code
+- How to contribute your extensions back to the oCIS community
+
+**Time investment:** ~10-14 hours per extension (concept to production-ready)
+
+**Cost:** ~$70 CAD for two extensions (using Claude Max Pro subscription)
+
+## Background
+
+When Google started pushing notifications telling my family we were at or close to our storage limits—with helpful suggestions to upgrade to a paid plan—I decided to solve the problem by enhancing our self-hosted oCIS instance with better photo browsing capabilities.
+
+The existing oCIS file browser shows thumbnails, which is functional, but I wanted what Google Photos gave us: timeline views organised by capture date, camera metadata at a glance, and a map showing where photos were taken.
+
+Using AI-assisted development, I built two fully functional web extensions and contributed backend changes to oCIS core—all without writing a single line of code by hand.
+
+## Prerequisites
+
+Before starting, ensure you have the following:
+
+- A running oCIS instance
+- Claude Max Pro subscription (~$140 CAD/month)
+- SSH access to your server (for MCP connectivity)
+- Full root access to the server unless Claude Code, Claude MCP connector, oCIS and other tools all run as another user
+
+That's it. Claude will help you install everything else.
+
+## Step 1: Configure MCP Connector
+
+{{< hint type=important title="This Is the Hardest Part" >}}
+Setting up the MCP connector is the most challenging step. Once this is done, Claude handles everything else—including installing development tools, managing git, and building your extension.
+{{< /hint >}}
+
+MCP (Model Context Protocol) allows Claude to connect directly to your server, enabling both the Claude web interface and Claude Code to access files, run commands, and debug your oCIS deployment.
+
+### Installation
+
+Follow the official MCP documentation to set up your connector:
+
+- **MCP Quickstart Guide**: https://modelcontextprotocol.io/quickstart
+- **Connect to Local Servers**: https://modelcontextprotocol.io/docs/develop/connect-local-servers
+- **Claude Desktop MCP Setup**: https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop
+
+### Verify Connection
+
+Once configured, verify Claude can access your server by asking:
+
+```
+Can you list the contents of /home on my server?
+```
+
+If Claude successfully lists your directories, you're ready to proceed.
+
+## Step 2: Let Claude Set Up Your Environment
+
+With MCP connected, Claude can install the development tools you need. Simply ask:
+
+```
+Please install Claude Code and Git on my server. I'll need these for 
+developing an oCIS web extension.
+```
+
+Claude will:
+- Detect your operating system
+- Install Claude Code using the appropriate method
+- Install Git if not already present
+- Configure any necessary paths or permissions
+
+## The Five-Phase Workflow
+
+This workflow has been refined over several projects and consistently produces production-ready code.
+
+### Phase 1: Architecture (~15-30 minutes)
+
+Start in the Claude web interface (not Claude Code). Describe your project and have a conversation:
+
+```
+I want to build an oCIS web extension that displays photos in a timeline 
+grouped by their EXIF capture date. It should have infinite scroll starting 
+from today and going backwards, show camera metadata when you click on a photo, 
+and include an interactive map view showing where photos were taken.
+
+What questions do you have about the requirements?
+```
+
+Claude will ask clarifying questions about scope, user experience, and technical constraints. This back-and-forth shapes the architecture before any code is written.
+
+### Phase 2: Deep Research (~30 minutes)
+
+Ask Claude to research the existing oCIS architecture:
+
+```
+Please research how oCIS web extensions work. I need to understand:
+- The extension manifest format
+- How extensions integrate with the oCIS web UI
+- What APIs are available (Graph API, WebDAV, etc.)
+- How existing extensions like json-viewer are structured
+- The AMD module format requirements
+
+Examine the oCIS documentation and existing extensions to synthesise 
+a technical approach for my photo gallery extension.
+```
+
+Claude reads documentation, examines code patterns, and produces an architectural plan.
+
+### Phase 3: Scaffolding (~15 minutes)
+
+Now ask Claude to create the project structure on your server:
+
+```
+Please create the project structure for my photo-addon extension:
+- Git repository initialised
+- Build configuration (Vite with AMD output)
+- TypeScript configuration
+- manifest.json for oCIS
+- Basic Vue 3 component structure
+- A starter CLAUDE.md file documenting the project for future sessions
+```
+
+By the end of this phase, you have a working (empty) extension.
+
+### Phase 4: Implementation (~5-6 hours)
+
+Login to your server and changes the folder where the new project was created, and run: 
+```
+claude "Please review the claude.md project file, build the web exention, and deploy it to our server. Install and configure any dependencies required. Use 'sudo' where needed to modify or configure the oCIS environment."
+```
+Once complete, work through features incrementally. Example prompts:
+
+**Feature requests:**
+```
+Please adjust the logic to start by searching for today's date (unless 
+overwritten by the dropdowns at the top), then display them on the screen. 
+If the images don't fill the screen, load up another day, until the screen 
+is filled plus some buffer. Then when I scroll, bring in more images.
+```
+
+```
+In the map view, when I hover over a dot, the thumbnail shows up above 
+off the screen. Can you fix the positioning?
+```
+
+**Bug fixes:**
+```
+I'm seeing this error in the console:
+[paste error here]
+
+Can you investigate and fix it?
+```
+
+### Phase 5: Polish (~3 hours)
+
+Once core features work, request comprehensive cleanup. Here are the prompts I used:
+
+**Performance optimisation:**
+```
+Are there any performance improvements that we can make?
+```
+
+**Bug hunting:**
+```
+Are there any memory leaks or bugs that can be found?
+```
+
+**Code quality:**
+```
+Are there any inefficiencies we can improve on? Unused variables? 
+Duplicate functions? Excessive if statements? Overwriting CSS styles? 
+Overly complex logic?
+```
+
+**Error handling:**
+```
+Are there any error handling gaps or functions that may fall through 
+without handling all scenarios?
+```
+
+**Documentation:**
+```
+Are there any missing comments? Or complex code that could use 
+clear documentation?
+```
+
+**Internationalisation:**
+```
+Are there any visible text strings that are not yet set up for translation?
+```
+
+**Comprehensive cleanup:**
+```
+Pulling from the backlog list, can you do a good code refactor to simplify, 
+add all required unit tests, and add i18n support, then commit and push the 
+code with the right comments.
+```
+
+## Active Supervision
+
+{{< hint type=warning title="This is NOT 'Set It and Forget It'" >}}
+While no coding is required, this approach demands active supervision. You cannot just give Claude a prompt and walk away.
+{{< /hint >}}
+
+### When to Intervene
+
+There were times when Claude Code would:
+- Deviate from requirements (with good intentions)
+- Undo something it had just done
+- Go down a path that didn't match the architecture
+
+The decisions were always logical, but sometimes the harder path is required. I estimate intervening to redirect maybe 3-5% of the time.
+
+**Watch for:**
+- Changes that don't match your architectural decisions
+- Unnecessary complexity being added
+- Repeated undo/redo cycles
+- Deviation from oCIS extension patterns
+
+### Code Cleanup Is Essential
+
+AI-generated code works, but it can accumulate:
+- Redundant logic
+- Unused variables
+- Overly complex conditionals
+- Duplicate CSS styles
+
+Explicitly asking for refactoring and optimisation catches these issues.
+
+### UI Testing Is On You
+
+The AI can write unit tests, but exploratory testing requires human judgment:
+- Click around the interface
+- Try unexpected inputs
+- Test with different user accounts (search in oCIS is space-scoped!)
+- Check mobile layouts
+- Look for edge cases
+
+## Debugging Techniques
+
+When issues arise, these techniques help Claude understand and fix problems:
+
+### Console Output
+
+Open Chrome DevTools, copy console errors, and paste into Claude:
+
+```
+I'm seeing this error in the console:
+[paste error here]
+
+Can you investigate and fix it?
+```
+
+### HAR Files
+
+For performance issues, export HAR files (network traffic captures):
+
+1. Open DevTools > Network tab
+2. Reproduce the issue
+3. Right-click > Save all as HAR
+4. Share the HAR file with Claude for analysis
+
+### HTML/CSS Inspection
+
+Copy specific HTML/CSS snippets from DevTools:
+
+```
+The thumbnail hover popup is positioned incorrectly. Here's the current 
+CSS and HTML structure:
+[paste code here]
+
+Can you fix the positioning so the popup appears above the cursor 
+but stays within the viewport?
+```
+
+{{< hint type=tip title="Chrome Extension Limitations" >}}
+Claude has a Chrome extension, but I found it primitive for this use case. Manually copying console output and HTML/CSS snippets into Claude was more effective.
+{{< /hint >}}
+
+## What I Built
+
+### Photo Gallery Extension (web-app-photos)
+
+Features:
+- **Timeline View**: Photos grouped by EXIF capture date with infinite scroll
+- **Pinch-to-zoom calendar**: Navigate between day, month, and year views
+- **EXIF Metadata Panel**: Camera make/model, aperture, ISO, focal length
+- **Map View**: Interactive Leaflet map with marker clustering
+- **Lightbox**: Full-screen viewer with keyboard navigation
+
+Tech stack: Vue 3 Composition API, TypeScript, Leaflet.js, AMD module format
+
+### Advanced Search Extension (web-app-advanced-search)
+
+Features:
+- **Photo Metadata Filters**: Search by camera, date range, aperture, ISO
+- **Filter Chips**: Visual indicators with one-click removal
+- **Search Saving**: Save and retrieve search queries
+- **KQL Search**: Direct advanced query editing
+- **Index Statistics**: View indexing status and configuration
+
+### Backend Changes (PR #11912)
+
+To enable photo metadata search, I contributed changes to oCIS core:
+- Photo field mappings in the KQL parser
+- `Store=true` configuration in Bleve for field retrieval
+- WebDAV properties for photo metadata
+
+This was the trickiest part—understanding why searches returned empty results. The answer: Bleve was indexing fields but not storing them for retrieval.
+
+## Tips for oCIS Development
+
+### 1. Start with Conversation, Then Architecture
+
+Don't jump straight into implementation. Spend ~30-60 minutes in regular chat, discussing the problem space and having Claude research the codebase. I still don't fully understand all of the oCIS source code—Claude figured that out. But those early conversations shaped the architecture that made implementation smooth.
+
+### 2. Work Incrementally
+
+Ask for one feature at a time. Get it working, then move to the next. This creates natural checkpoints and makes debugging much easier.
+
+### 3. Use Browser DevTools Liberally
+
+Console errors, network requests, and performance profiles are incredibly valuable context. Copy and paste them into your AI conversation.
+
+### 4. Understand oCIS Extension Requirements
+
+Extensions must:
+- Use AMD module format (not ES modules)
+- Have a proper `manifest.json`
+- Use the oCIS web SDK for API access
+
+Claude learns these constraints during the research phase and applies them consistently.
+
+### 5. Test with Multiple Accounts
+
+Search in oCIS is space-scoped. What works for your admin account might not work for regular users. I spent more time on this than I'd like to admit.
+
+### 6. Read Maintainer Feedback Carefully
+
+PR reviews teach you things no documentation mentions. The oCIS team's suggestions improved my code significantly.
+
+## Contributing to oCIS
+
+Once your extension is ready, Claude can handle the entire contribution workflow. I used Claude to:
+
+- Install and configure Git
+- Create forks of the oCIS repositories
+- Create feature branches
+- Generate commits with appropriate messages
+- Push changes to GitHub
+- Create pull requests with descriptions and screenshots
+
+Example prompts:
+
+```
+Please fork the owncloud/web-extensions repository to my GitHub account 
+and clone it to my server.
+```
+
+```
+Create a new branch called feat/web-app-photo-addon and commit our 
+extension with an appropriate commit message.
+```
+
+```
+Please create a pull request for our photo-addon extension. Include 
+screenshots from the /screenshots directory and a clear description 
+of what the extension does.
+```
+
+**My contributions:**
+- **PR #11912** (oCIS core): Photo metadata search backend — **Merged**
+- **PR #305** (web-extensions): Photo gallery extension — Under review
+- **PR #306** (web-extensions): Advanced search extension — Under review
+
+{{< hint type=note title="CLA Requirement" >}}
+You'll need to sign the ownCloud Contributor License Agreement (CLA) for your PRs to be accepted. Claude can help you find the CLA link and remind you of the process.
+{{< /hint >}}
+
+## Summary
+
+**Not a single line of code was written by hand. Not a single git command was typed manually. Nor a single pnpm command.**
+
+Every commit, every push, every PR—all generated through AI assistance. The backend changes to oCIS core were approved and merged. The web extensions are currently under review.
+
+The barrier to entry for meaningful open source contribution just got a lot lower. If you're interested in contributing to oCIS but feel intimidated by the codebase, consider trying AI-assisted development. It will surprise you.
+
+And if you're sceptical? Good. Try it yourself and see.
+
+---
+
+## Resources
+
+| Resource | URL |
+|----------|-----|
+| My Extensions | https://github.com/paul43210/web-extensions |
+| MCP Quickstart | https://modelcontextprotocol.io/quickstart |
+| MCP Local Servers | https://modelcontextprotocol.io/docs/develop/connect-local-servers |
+| Claude Desktop MCP | https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop |
+| oCIS Web Extensions | https://github.com/owncloud/web-extensions |
+| oCIS Documentation | https://doc.owncloud.com/ocis/ |
+
+---
+
+*Paul Faure is a computer engineer based in Ottawa, Canada. He runs a family oCIS instance that he now enjoys using for photos.*
+
+*Full disclosure: this guide was also written with AI assistance. But a human reviewed it for accuracy—I promise.*