Skip to content

Commit 02097d0

Browse files
CopilotR0Wi
Copilot
and
R0Wi
authored
Add Copilot instructions for workflow_ocr repository (#348)
* Initial plan * Add Copilot instructions for workflow_ocr repository Co-authored-by: R0Wi <19730957+R0Wi@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: R0Wi <19730957+R0Wi@users.noreply.github.com>
1 parent 814132a commit 02097d0

File tree

1 file changed

+245
-0
lines changed

1 file changed

+245
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
# Copilot Instructions for workflow_ocr
2+
3+
## Repository Overview
4+
5+
This repository contains the `workflow_ocr` Nextcloud app, which enables flexible OCR (Optical Character Recognition) processing through Nextcloud's workflow engine. The app processes PDF files and images using [OCRmyPDF](https://github.com/ocrmypdf/OCRmyPDF) to add searchable text layers.
6+
7+
## Architecture
8+
9+
### Core Concepts
10+
11+
The app integrates with Nextcloud's [workflowengine](https://github.com/nextcloud/server/tree/master/apps/workflowengine) to allow administrators and users to configure OCR tasks that run as scheduled background jobs.
12+
13+
### Backend Modes
14+
15+
The app supports two OCR processing modes:
16+
17+
1. **Local Mode**: `ocrmypdf` runs on the same server as Nextcloud. The app calls the CLI and interacts via stdin/stdout.
18+
19+
2. **External Backend Mode**: Uses the [`workflow_ocr_backend`](https://github.com/R0Wi-DEV/workflow_ocr_backend) ExApp (External App) running in a separate Docker container connected to the Nextcloud instance. Files and parameters are sent via REST API.
20+
21+
### Key Components
22+
23+
- **OcrProcessors** (`lib/OcrProcessors/`): Handle different file types (PDF, JPEG, PNG)
24+
- **Background Jobs** (`lib/BackgroundJobs/`): Process OCR tasks asynchronously
25+
- **Workflow Operations** (`lib/Operation.php`): Integration with Nextcloud workflow engine
26+
- **Settings** (`lib/Settings/`): Per-workflow and global configuration
27+
- **Notifications**: User feedback for OCR processing results
28+
29+
## Development Requirements
30+
31+
### Critical Context
32+
33+
**IMPORTANT**: This app cannot run standalone. For development, you MUST:
34+
35+
1. Set up a full [Nextcloud Server](https://github.com/nextcloud/server) instance
36+
2. Install this app into the Nextcloud installation
37+
3. Tests must run within a working Nextcloud environment (see CI/CD workflows for examples)
38+
39+
### Target Version Compatibility
40+
41+
Always check `appinfo/info.xml` for the Nextcloud target version:
42+
- If the version exists (e.g., NC 32), check against that stable branch in the Nextcloud Server repo
43+
- If the version doesn't exist yet (e.g., NC 33 not released), check against the `master` branch of the Nextcloud Server repo
44+
45+
Current target: Nextcloud 33 (check `appinfo/info.xml` for updates)
46+
47+
### Technology Stack
48+
49+
- **Backend**: PHP 8.1-8.4
50+
- **Frontend**: Vue 3, Node 24, npm 11.6
51+
- **Build Tools**: rspack, vitest, eslint, stylelint
52+
- **PHP Tools**: composer, phpunit, psalm, php-cs-fixer
53+
- **External Dependencies**: OCRmyPDF CLI, tesseract-ocr
54+
55+
### Required Tools
56+
57+
- `make`
58+
- `node` and `npm` (versions specified in package.json)
59+
- `composer`
60+
- PHP 8.1+ environment
61+
- Web server (Apache recommended)
62+
- XDebug (for debugging)
63+
64+
## Building and Testing
65+
66+
### Build Commands
67+
68+
```bash
69+
# Full build (installs dependencies and compiles)
70+
make build
71+
72+
# Install composer dependencies only
73+
make composer-build
74+
75+
# Install and build frontend
76+
make npm-install && make npm-build
77+
```
78+
79+
### Testing
80+
81+
**IMPORTANT**: Activate the app before running tests: `php occ app:enable workflow_ocr`
82+
83+
```bash
84+
# Run all tests
85+
make test
86+
87+
# PHP unit tests only
88+
make php-unittest
89+
90+
# PHP integration tests only
91+
make php-integrationtest
92+
93+
# JavaScript tests
94+
make js-test
95+
96+
# Generate coverage
97+
make coverage-all
98+
```
99+
100+
### Linting
101+
102+
```bash
103+
# Check all linting (PHP and JS)
104+
make lint
105+
106+
# Auto-fix linting issues
107+
make lint-fix
108+
109+
# PHP only
110+
composer run cs:check
111+
composer run cs:fix
112+
composer run psalm
113+
114+
# JS only
115+
npm run lint
116+
npm run lint:fix
117+
```
118+
119+
## Coding Conventions
120+
121+
### General Principles
122+
123+
1. **Minimal Changes**: Make the smallest possible modifications to achieve the goal
124+
2. **Existing Patterns**: Follow established patterns in the codebase
125+
3. **Nextcloud Compatibility**: Always verify changes against the target Nextcloud Server version code
126+
4. **No Standalone Assumptions**: Remember the app must work within Nextcloud ecosystem
127+
128+
### PHP Conventions
129+
130+
- Follow Nextcloud coding standards (enforced by `php-cs-fixer`)
131+
- Use type hints and return types
132+
- Namespace: `OCA\WorkflowOcr\`
133+
- PSR-4 autoloading from `lib/` directory
134+
- Use dependency injection via Nextcloud's container
135+
136+
### JavaScript/Vue Conventions
137+
138+
- Vue 3 Composition API
139+
- Use Nextcloud Vue components from `@nextcloud/vue`
140+
- Follow ESLint configuration (`@nextcloud/eslint-config`)
141+
- Use l10n for all user-facing strings (`@nextcloud/l10n`)
142+
143+
### File Organization
144+
145+
- **Controllers**: `lib/Controller/` - Handle HTTP requests
146+
- **Services**: `lib/Service/` - Business logic
147+
- **Models**: `lib/Model/` - Data structures
148+
- **Events**: `lib/Events/` - Event definitions
149+
- **Listeners**: `lib/Listener/` - Event handlers
150+
- **Background Jobs**: `lib/BackgroundJobs/` - Async processing
151+
- **Tests**: `tests/` - Unit and integration tests
152+
153+
### Adding New OcrProcessors
154+
155+
To support a new MIME type:
156+
157+
1. Create new class in `lib/OcrProcessors/` implementing `IOcrProcessor`
158+
2. Register in `lib/OcrProcessors/OcrProcessorFactory.php` mapping
159+
3. Add factory method in `registerOcrProcessors()`
160+
161+
## Branching Strategy
162+
163+
The repository follows the same branching strategy as Nextcloud Server:
164+
165+
- **`master`**: Development branch targeting the next unreleased Nextcloud version
166+
- **`stable##`**: Released stable versions (e.g., `stable32` for Nextcloud 32)
167+
168+
When working on code:
169+
- Changes for unreleased NC versions → `master` branch
170+
- Changes for released NC versions → appropriate `stable##` branch
171+
- Check [Nextcloud releases](https://github.com/nextcloud/server/releases) to determine which versions are released
172+
173+
## Nextcloud Integration
174+
175+
### Workflow Engine Integration
176+
177+
The app extends Nextcloud's workflow engine:
178+
- Left side (triggers/conditions): Provided by Nextcloud core
179+
- Right side (OCR settings): App-specific implementation
180+
181+
### Key Nextcloud APIs
182+
183+
- File system operations: `OCP\Files\File`, `OCP\Files\Folder`
184+
- Background jobs: `OCP\BackgroundJob\QueuedJob`
185+
- Events: `OCP\EventDispatcher\IEventDispatcher`
186+
- Settings: `OCP\Settings\ISettings`
187+
- Notifications: Via Nextcloud Notifications app
188+
189+
### Setup Checks
190+
191+
The app implements Nextcloud's Setup Check API to validate:
192+
- OCRmyPDF availability and version
193+
- Backend configuration
194+
- Required dependencies
195+
196+
## Common Tasks
197+
198+
### Running OCR Processing Manually
199+
200+
```bash
201+
cd /var/www/<NEXTCLOUD_INSTALL>
202+
sudo -u www-data php cron.php
203+
```
204+
205+
### Debugging
206+
207+
Use the provided VSCode configuration (`.vscode/launch.json`):
208+
- **Listen for XDebug**: Web server debugging
209+
- **Listen for XDebug (CLI)**: CLI debugging
210+
- **Run cron.php**: Debug background jobs
211+
- **Debug Unittests/Integrationtests**: Debug tests
212+
213+
Configure XDebug to connect on port 9003.
214+
215+
### Checking Logs
216+
217+
Set Nextcloud log level to 0 for detailed debugging:
218+
- Check `nextcloud.log` or use the logreader app
219+
- OCR process output is logged
220+
- Background job execution is logged
221+
222+
## Known Limitations
223+
224+
- Only PDF (`application/pdf`) and images (`image/jpeg`, `image/png`) are supported
225+
- All outputs are PDF files
226+
- PDF metadata may not be preserved (OCRmyPDF limitation)
227+
- No batch processing mechanism (use "tag assigned" trigger for existing files)
228+
- File versions can restore original files if needed
229+
230+
## External Resources
231+
232+
- [OCRmyPDF Documentation](https://ocrmypdf.readthedocs.io/)
233+
- [Nextcloud Server Repository](https://github.com/nextcloud/server)
234+
- [Nextcloud Workflow Engine](https://github.com/nextcloud/server/tree/master/apps/workflowengine)
235+
- [Nextcloud AppAPI](https://docs.nextcloud.com/server/latest/admin_manual/exapps_management/AppAPIAndExternalApps.html)
236+
- [workflow_ocr_backend](https://github.com/R0Wi-DEV/workflow_ocr_backend)
237+
238+
## Important Notes for AI Assistants
239+
240+
1. **Never assume standalone operation** - All development and testing requires a Nextcloud instance
241+
2. **Check Nextcloud Server code** - Always verify implementations against the target Nextcloud version
242+
3. **Respect branching strategy** - Ensure changes are compatible with the target Nextcloud version
243+
4. **Follow existing patterns** - The codebase has established patterns for controllers, services, and processors
244+
5. **Test within Nextcloud** - Tests cannot run in isolation; they need the Nextcloud environment
245+
6. **Consider both backends** - Changes may affect both local CLI and external backend processing modes

0 commit comments

Comments
 (0)