# Nextcloud Core Architecture

> >

- **Type:** Skill
- **Install:** `agentstack add skill-impertio-studio-nextcloud-claude-skill-package-nextcloud-core-architecture`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Impertio-Studio](https://agentstack.voostack.com/s/impertio-studio)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Impertio-Studio](https://github.com/Impertio-Studio)
- **Source:** https://github.com/Impertio-Studio/Nextcloud-Claude-Skill-Package/tree/main/skills/source/nextcloud-core/nextcloud-core-architecture

## Install

```sh
agentstack add skill-impertio-studio-nextcloud-claude-skill-package-nextcloud-core-architecture
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# nextcloud-core-architecture

## Quick Reference

### Architecture Layers (NC 28+)

| Layer | Technology | Location | Role |
|-------|-----------|----------|------|
| PHP Backend | PHP 8.1+ | `lib/` | Controllers, services, database, business logic |
| Vue.js Frontend | Vue 2 (v8.x) / Vue 3 (v9.x) | `src/` | Single-page app UI with `@nextcloud/vue` components |
| Data Directory | Filesystem | `data/` | User files, app data, logs |
| Apps Directory | PHP + JS | `apps/` / `apps-extra/` | Modular app extensions |
| OCS API | REST + JSON/XML | `/ocs/v2.php/` | Structured API with envelope responses |
| WebDAV | RFC 4918 | `/remote.php/dav/` | File, calendar, and contact operations |

### Key Dependencies

| Package | Type | Purpose |
|---------|------|---------|
| `@nextcloud/vue` | npm | Vue.js component library (NC UI kit) |
| `@nextcloud/axios` | npm | Authenticated HTTP client |
| `@nextcloud/router` | npm | URL generation (`generateUrl`, `generateOcsUrl`) |
| `@nextcloud/initial-state` | npm | Server-to-client data transfer |
| `@nextcloud/event-bus` | npm | Frontend cross-component events |
| `@nextcloud/webpack-vue-config` | npm (dev) | Pre-configured webpack base |

### Critical Warnings

**NEVER** query services from other apps inside `register()` -- they may not be registered yet. ALWAYS use `boot()` for cross-app service dependencies.

**NEVER** omit the `` element in `appinfo/info.xml` -- auto-wiring will silently fail because the DI container cannot map `OCA\{Namespace}\*` classes to the `lib/` directory.

**NEVER** use `\OCP\Server::get()` for service resolution in new code -- it is a service locator anti-pattern that breaks testability. ALWAYS use constructor injection.

**NEVER** use `OCP\ILogger` -- deprecated since NC 24. ALWAYS inject `Psr\Log\LoggerInterface` instead.

**NEVER** put business logic in `Application.php` -- keep it in `Service/` classes. `Application.php` MUST only contain registration and boot wiring.

**NEVER** perform I/O or side effects in constructors -- constructors MUST only assign dependencies.

---

## Request Lifecycle

All HTTP requests follow this path:

```
index.php
  -> lib/base.php (init: auth backends, filesystem, logging)
    -> Load all enabled apps (appinfo/info.xml)
    -> Load navigation and pre-config files
    -> Load route definitions (appinfo/routes.php)
    -> Router matches URL to Controller method
      -> Middleware chain (beforeController -> controller -> afterController)
        -> Response rendered and returned
```

1. `index.php` loads `lib/base.php`, which abstracts web server differences and initializes core classes
2. Authentication backends, filesystem, and logging are bootstrapped
3. Each installed app is loaded based on its `appinfo/info.xml`
4. Route definitions from each app's `appinfo/routes.php` are loaded
5. The router matches the incoming URL to a controller method
6. The middleware chain processes the request and response

---

## App Lifecycle: IBootstrap

The `Application` class in `lib/AppInfo/Application.php` implements `IBootstrap` for a two-phase lifecycle:

### Phase 1: register() -- Lazy Registration

Called during app loading. ONLY use `IRegistrationContext` methods here:

```php
public function register(IRegistrationContext $context): void {
    $context->registerMiddleware(MyMiddleware::class);
    $context->registerServiceAlias(IMyInterface::class, MyImplementation::class);
    $context->registerEventListener(ItemCreatedEvent::class, ItemCreatedListener::class);
    $context->registerParameter('TableName', 'my_app_table');
}
```

### Phase 2: boot() -- Post-Registration Initialization

Called after ALL apps have completed `register()`. All services are now available:

```php
public function boot(IBootContext $context): void {
    $context->injectFn(function (IFooManager $manager) {
        $manager->registerCustomFoo(MyFooImpl::class);
    });
}
```

### Bootstrap Sequence

1. Nextcloud scans enabled apps for `lib/AppInfo/Application.php`
2. Apps with `IBootstrap` -> `register()` called (in app dependency order)
3. App load groups processed (filesystem, session, etc.)
4. All `Application` classes fully instantiated
5. All `boot()` methods called -- prior registrations guaranteed complete
6. Request routing begins

---

## Dependency Injection

Nextcloud uses auto-wiring as the primary DI mechanism (PSR-11 compatible container).

### How Auto-Wiring Resolves Parameters

1. **Type hints**: `SomeType $param` resolves via `$container->get(SomeType::class)`
2. **Parameter names**: `$variable` resolves via `$container->get('variable')`

### Predefined Parameters

| Parameter | Type | Value |
|-----------|------|-------|
| `$appName` | `string` | Application ID |
| `$userId` | `?string` | Current user ID (null if no session) |
| `$webRoot` | `string` | Nextcloud installation path |

### Auto-Wiring Requirements

1. `` MUST be declared in `appinfo/info.xml`
2. Array-style routes in `appinfo/routes.php`
3. Constructor parameters MUST have type hints

### IRegistrationContext Methods

| Method | Purpose |
|--------|---------|
| `registerService(string $class, Closure $factory)` | Explicit factory registration |
| `registerParameter(string $name, $value)` | Register primitive values |
| `registerServiceAlias(string $interface, string $impl)` | Interface-to-implementation binding |
| `registerEventListener(string $event, string $listener)` | Event listener registration |
| `registerMiddleware(string $class, bool $global = false)` | Middleware registration |

### Optional Dependencies (NC 28+)

Use nullable types for services that may not exist:

```php
class MyService {
    public function __construct(private ?SomeOptionalService $service) { }
}
```

---

## Key OCP Interfaces

| Interface | Purpose |
|-----------|---------|
| `OCP\AppFramework\App` | Base class for app entry point (`Application`) |
| `OCP\AppFramework\Bootstrap\IBootstrap` | Two-phase app lifecycle (register/boot) |
| `OCP\AppFramework\Bootstrap\IRegistrationContext` | Service registration during app loading |
| `OCP\AppFramework\Bootstrap\IBootContext` | Runtime operations after all apps registered |
| `OCP\IDBConnection` | Database abstraction (MySQL, PostgreSQL, SQLite, Oracle) |
| `OCP\IRequest` | HTTP request abstraction |
| `OCP\IConfig` | Server and app configuration |
| `OCP\IAppConfig` | App-specific configuration |
| `OCP\IUserManager` | User CRUD operations |
| `OCP\IUserSession` | Current user session management |
| `OCP\Files\IRootFolder` | Filesystem root access |
| `OCP\IURLGenerator` | URL generation for routes and assets |
| `OCP\ICacheFactory` | Cache factory |
| `OCP\Security\ICrypto` | Cryptographic operations |
| `OCP\IL10N` | Localization/translation |
| `OCP\AppFramework\Services\IInitialState` | Server-to-frontend state transfer |
| `OCP\EventDispatcher\IEventDispatcher` | Event dispatch service |
| `Psr\Log\LoggerInterface` | PSR-3 compliant logging (ALWAYS use this) |
| `Psr\Container\ContainerInterface` | PSR-11 DI container |

---

## Namespace Conventions

The `` element in `info.xml` determines the `OCA\{Namespace}` prefix. Nextcloud's autoloader maps this to the `lib/` directory:

| info.xml namespace | PHP namespace | File path |
|-------------------|---------------|-----------|
| `MyApp` | `OCA\MyApp\AppInfo\Application` | `lib/AppInfo/Application.php` |
| | `OCA\MyApp\Controller\PageController` | `lib/Controller/PageController.php` |
| | `OCA\MyApp\Service\ItemService` | `lib/Service/ItemService.php` |
| | `OCA\MyApp\Db\ItemMapper` | `lib/Db/ItemMapper.php` |
| | `OCA\MyApp\Listener\ItemListener` | `lib/Listener/ItemListener.php` |

---

## Project Structure

```
myapp/
├── appinfo/
│   ├── info.xml              # App manifest (REQUIRED)
│   └── routes.php            # Route definitions
├── lib/
│   ├── AppInfo/
│   │   └── Application.php   # Bootstrap entry point (IBootstrap)
│   ├── Controller/            # HTTP controllers
│   ├── Service/               # Business logic layer
│   ├── Db/                    # Entity classes and mappers
│   ├── Listener/              # Event listeners
│   ├── Middleware/             # Request middleware
│   ├── Migration/             # Database migrations
│   └── Command/               # OCC CLI commands
├── src/                       # Vue.js frontend source
│   ├── main.js                # Vue app entry point
│   ├── App.vue                # Root Vue component
│   ├── components/            # Reusable Vue components
│   ├── views/                 # Page-level components
│   ├── store/                 # Vuex/Pinia store
│   └── services/              # API service layer
├── css/                       # Stylesheets (CSS/SCSS)
├── img/                       # Icons (app.svg = app icon)
├── js/                        # Compiled JS output (generated)
├── templates/                 # PHP templates
├── tests/                     # PHPUnit tests
├── l10n/                      # Translation files
├── webpack.config.js          # Build configuration
└── package.json               # NPM dependencies
```

### Source Control Rules

- **ALWAYS commit**: `composer.lock`, `package-lock.json` (deterministic builds)
- **ALWAYS ignore**: `vendor/`, `node_modules/`, `js/` (build artifacts)
- **NEVER edit**: generated files in `js/` directory

---

## Reference Links

- [references/methods.md](references/methods.md) -- Key interfaces: App, IBootstrap, IRegistrationContext, IServerContainer, core services
- [references/examples.md](references/examples.md) -- Application.php, DI patterns, service layer examples
- [references/anti-patterns.md](references/anti-patterns.md) -- DI mistakes, bootstrap errors, common pitfalls

### Official Sources

- https://docs.nextcloud.com/server/latest/developer_manual/app_development/intro.html
- https://docs.nextcloud.com/server/latest/developer_manual/app_development/bootstrap.html
- https://docs.nextcloud.com/server/latest/developer_manual/basics/dependency_injection.html
- https://docs.nextcloud.com/server/latest/developer_manual/app_development/info.html

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Impertio-Studio](https://github.com/Impertio-Studio)
- **Source:** [Impertio-Studio/Nextcloud-Claude-Skill-Package](https://github.com/Impertio-Studio/Nextcloud-Claude-Skill-Package)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-impertio-studio-nextcloud-claude-skill-package-nextcloud-core-architecture
- Seller: https://agentstack.voostack.com/s/impertio-studio
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.