|
| 1 | +<!-- Generic guidance for all coding agents (Claude Code, Zed, Cursor, etc.) --> |
| 2 | + |
| 3 | +# Kolibri Studio Development Guide for AI Coding Agents |
| 4 | + |
| 5 | +**Project:** Kolibri Studio — web app for authoring and publishing learning channels to Kolibri |
| 6 | +**Stack:** Python/Django backend, Vue.js 2.7 frontend, Kolibri Design System (KDS) + legacy Vuetify 1.5, Postgres/Redis/MinIO/Celery services, pytest/Jest testing |
| 7 | +**Platform:** web (server-deployed, not packaged for clients) |
| 8 | + |
| 9 | +## Quick Start |
| 10 | + |
| 11 | +```bash |
| 12 | +uv pip sync requirements.txt requirements-dev.txt # Python deps |
| 13 | +pnpm install # Node deps |
| 14 | +pre-commit install # Required — commits fail without this |
| 15 | +make dcservicesup # Bring up postgres / redis / minio in docker |
| 16 | +pnpm devsetup # Migrate + load sample data + create admin |
| 17 | +pnpm devserver # Django :8080 + Webpack watcher |
| 18 | +``` |
| 19 | + |
| 20 | +→ Full setup: `README.md` | Local production-shape stack: `make dcup` (uses `docker-compose.yml`) |
| 21 | + |
| 22 | +## Critical Gotchas |
| 23 | + |
| 24 | +### ⚠️ BEFORE Writing Any Vue Component, Search for Existing Ones |
| 25 | + |
| 26 | +Do not create a new component without first searching for an existing solution: |
| 27 | +1. **Kolibri Design System** ([docs](https://design-system.learningequality.org/)) — `KButton`, `KCircularLoader`, `KTextbox`, `KSelect`, `KModal`, `KCheckbox`, `KIcon`, `KTable`, etc. |
| 28 | +2. **`contentcuration/contentcuration/frontend/shared/`** — Studio-specific shared components. |
| 29 | +3. **Vuetify 1.5** — for legacy widgets KDS doesn't cover (data tables, complex layout primitives). See the next gotcha before reaching for Vuetify in new code. |
| 30 | + |
| 31 | +If a component does 80% of what you need, wrap it — do not rewrite. |
| 32 | + |
| 33 | +### ⚠️ Use KDS, Not Vuetify, for New Code |
| 34 | + |
| 35 | +KDS is the design-system source of truth. Vuetify is legacy and being phased out. **Do not introduce Vuetify into a fresh component** — new files use KDS. When you're already editing a file for another reason and a Vuetify widget in it has a KDS equivalent, migrating it is welcome — **keep it small and in-scope** (the component you're touching, not a sweep of the whole file). Don't open unrelated PRs solely to migrate, and don't half-convert a component and leave it mixed. |
| 36 | + |
| 37 | +### ⚠️ Use Theme Tokens, Not Hard-Coded Colors |
| 38 | + |
| 39 | +Never use raw color values. Access theme colors via `$themeTokens` and `$themePalette`: |
| 40 | +```vue |
| 41 | +<template> |
| 42 | + <div :style="{ color: $themeTokens.text, backgroundColor: $themeTokens.surface }"> |
| 43 | + <span :style="{ color: $themeTokens.annotation }">secondary text</span> |
| 44 | + </div> |
| 45 | +</template> |
| 46 | +``` |
| 47 | +For computed dynamic styles, use `$computedClass`. |
| 48 | + |
| 49 | +### ⚠️ Style Blocks, Not Inline — RTL Depends On It |
| 50 | + |
| 51 | +Non-dynamic styles go in `<style>` blocks. RTLCSS auto-flips directional properties (`padding-left` → `padding-right`) in style blocks but **cannot flip inline styles**. Dynamic directional styles must check `isRtl`. |
| 52 | + |
| 53 | +### ⚠️ Prefer Composition API for New Code |
| 54 | + |
| 55 | +Studio's existing code is largely Options API, but new components and refactors should use Composition API. It's fine to add Composition API to an existing Options API file when the existing logic isn't worth restructuring — be aware that a partial mix usually leads to a follow-up refactor. |
| 56 | + |
| 57 | +### ⚠️ No New Vuex — Use Composition API for New State |
| 58 | + |
| 59 | +Vuex 3 is deprecated in Studio. **New state goes through Composition API** — composables built on `ref`/`reactive`/`computed`, scoped to the consuming component or a `provide`/`inject` boundary. Existing Vuex modules live under `frontend/<app>/vuex/` (including the IndexedDB-backed sync store); when you're already editing code that leans on one and the slice is small, moving it to a composable is welcome — **keep it small and in-scope**, don't restructure a whole module in an unrelated PR. Leave the sync store alone unless the work is specifically about it. |
| 60 | + |
| 61 | +### ⚠️ Studio Uses an IndexedDB-Backed Change-Sync Architecture — Don't Mutate Synced Models Directly |
| 62 | + |
| 63 | +Edits in the editor write to Dexie tables in the browser via the Resource layer (`contentcuration/contentcuration/frontend/shared/data/`), which generates Change records that flow to the server's `/api/sync/` endpoint (`contentcuration/contentcuration/viewsets/sync/`). The server applies changes via a change-type registry (`viewsets/sync/base.py`, `viewsets/sync/constants.py`) and broadcasts back. |
| 64 | + |
| 65 | +Direct `axios.post` or direct ORM `save()` on a synced model bypasses the change pipeline and corrupts the offline → online merge. **Rule:** if a model is part of the sync framework, all writes go through the Resource layer (frontend) or the change-application registry (backend). Backend system-internal operations (publishing, garbage collection) may bypass; anything user-facing must not. See `CLAUDE.md` for a fuller description. |
| 66 | + |
| 67 | +### ⚠️ Responsive Layout: Plain CSS First, Vuetify Grid Only as a Last Resort |
| 68 | + |
| 69 | +New layout uses plain `<div>`s with CSS (flexbox/grid) in a `<style>` block, plus KDS's `useKResponsiveWindow` composable when a breakpoint has to drive logic: |
| 70 | +```javascript |
| 71 | +import useKResponsiveWindow from 'kolibri-design-system/lib/composables/useKResponsiveWindow'; |
| 72 | + |
| 73 | +const { windowIsSmall, windowWidth } = useKResponsiveWindow(); |
| 74 | +``` |
| 75 | +Vuetify's `v-container` / `v-row` / `v-col` grid is legacy, like the rest of Vuetify. Inside a file that already uses it, leave it alone — no refactor required. Reach for it in new code only when plain CSS genuinely can't express the layout. |
| 76 | + |
| 77 | +### ⚠️ Internationalize All User-Visible Text |
| 78 | + |
| 79 | +Use `createTranslator` from `shared/i18n` (Studio re-exports Kolibri's i18n there) — never hard-code strings in templates: |
| 80 | +```javascript |
| 81 | +import { createTranslator } from 'shared/i18n'; |
| 82 | + |
| 83 | +const strings = createTranslator('ChannelStrings', { |
| 84 | + title: { message: 'Channel title', context: 'Form field label' }, |
| 85 | +}); |
| 86 | +const { title$ } = strings; // title$() returns the translated string |
| 87 | +``` |
| 88 | + |
| 89 | +### ⚠️ API Calls via the Resource Pattern |
| 90 | + |
| 91 | +For synced models, use the Resource layer in `contentcuration/contentcuration/frontend/shared/data/` (see sync gotcha above). For non-synced endpoints, use the existing Resource-style wrappers in `shared/data/resources.js`. Never use raw `fetch` or `axios` for domain operations. |
| 92 | + |
| 93 | +### ⚠️ Backend APIs: Use `ValuesViewset` |
| 94 | + |
| 95 | +Studio has `ValuesViewset` / `ReadOnlyValuesViewset` vendored at `contentcuration/contentcuration/viewsets/base.py`. Use them for new API endpoints — define a `values` tuple and `annotate_queryset` for computed fields rather than relying on default serializer output. Apply permission classes from `contentcuration/contentcuration/viewsets/`. |
| 96 | + |
| 97 | +### ⚠️ Testing Is Required |
| 98 | + |
| 99 | +- **Python:** `pytest` from repo root (uses `pytest.ini` → `contentcuration.test_settings`). Django API tests extend `APITestCase` from `rest_framework.test`. Other Django tests extend `django.test.TestCase`. |
| 100 | +- **Frontend:** Jest runner + Vue Testing Library via `@testing-library/vue` (`render`). Write new tests with VTL. `@vue/test-utils` (`mount`/`shallowMount`) still appears in many existing tests but is **deprecated** — there are open issues to remove those tests, so do not add new ones. `describe`/`it`/`expect` are Jest globals — do NOT import them. Use `jest.fn()` and `jest.mock()`. |
| 101 | +- **TDD:** Write a failing test first, then make it pass. Especially for bug fixes — always write a test that reproduces the bug before fixing it. |
| 102 | + |
| 103 | +### ⚠️ Pre-commit Auto-Fixes Files |
| 104 | + |
| 105 | +When a commit fails: pre-commit auto-fixes files → **`git add` the fixed files** → re-commit. Never bypass with `--no-verify`. |
| 106 | + |
| 107 | +## Project Structure |
| 108 | + |
| 109 | +``` |
| 110 | +studio/ |
| 111 | +├── contentcuration/ # Django project root (also contains other apps) |
| 112 | +│ ├── contentcuration/ # Main Django app |
| 113 | +│ │ ├── frontend/ # Vue source |
| 114 | +│ │ │ ├── channelEdit/ |
| 115 | +│ │ │ ├── channelList/ |
| 116 | +│ │ │ ├── settings/ |
| 117 | +│ │ │ ├── accounts/ |
| 118 | +│ │ │ ├── administration/ |
| 119 | +│ │ │ └── shared/ # Shared components + sync data layer |
| 120 | +│ │ ├── viewsets/ # DRF ValuesViewsets — sync/ contains the change framework |
| 121 | +│ │ ├── models.py, urls.py, settings.py, dev_settings.py, test_settings.py |
| 122 | +│ │ └── static/studio/ # webpack output (git-ignored) |
| 123 | +│ ├── automation/ # Django app — automation workflows |
| 124 | +│ ├── kolibri_content/ # Django app — Kolibri content schema |
| 125 | +│ ├── kolibri_public/ # Django app — public catalog API |
| 126 | +│ ├── search/ # Django app — full-text search |
| 127 | +│ ├── manage.py |
| 128 | +│ └── build/ # webpack-stats.json (git-ignored) |
| 129 | +├── docker/ # Dockerfile.{dev,prod,nginx.prod,postgres.dev} |
| 130 | +├── integration_testing/ |
| 131 | +│ ├── features/ # Gherkin BDD specs (manual reference) |
| 132 | +│ └── smoke_test.py # CI smoke test |
| 133 | +├── jest_config/ # Jest config |
| 134 | +├── webpack.config.js |
| 135 | +├── Makefile # dc* targets + altprodserver |
| 136 | +└── docker-compose.yml / docker-compose.prod.yml |
| 137 | +``` |
| 138 | + |
| 139 | +**Settings split:** |
| 140 | +- `contentcuration.dev_settings` — local development. Use this for local `manage.py` commands. |
| 141 | +- `contentcuration.settings` — production. Used by `make altprodserver` and the CI smoke test. |
| 142 | +- `contentcuration.test_settings` — pytest. |
| 143 | + |
| 144 | +## Code Quality |
| 145 | + |
| 146 | +Studio follows the same code-quality principles as Kolibri. → See https://kolibri-dev.readthedocs.io/en/latest/code_quality.html.md for detailed examples (LLM-friendly Markdown version; drop `.md` for the HTML rendering). |
| 147 | + |
| 148 | +## Key Conventions |
| 149 | + |
| 150 | +**Python:** F-strings preferred. One import per line. All imports at file top — inline imports only to prevent circular imports. Descriptive migration names (no `_auto_`). |
| 151 | + |
| 152 | +**Vue:** PascalCase filenames. Component `name` must match filename. |
| 153 | + |
| 154 | +**Git:** Imperative commit messages. **PR titles do NOT use Conventional Commits prefix** (e.g. `feat:`, `fix:`) — plain English titles. Individual commit messages may use CC prefixes. Black/Prettier enforced by pre-commit. |
| 155 | + |
| 156 | +**Don't guess — look at existing code** for patterns: `contentcuration/contentcuration/viewsets/` for API patterns, `contentcuration/contentcuration/frontend/shared/data/` for sync framework, existing `__tests__/` directories for test patterns. |
| 157 | + |
| 158 | +## Running Tests |
| 159 | + |
| 160 | +```bash |
| 161 | +pytest # all Python tests |
| 162 | +pytest contentcuration/contentcuration/tests/ -k name # filter by name |
| 163 | +pnpm test # all Jest tests |
| 164 | +pnpm jest --config jest_config/jest.conf.js <path> # single file |
| 165 | +pre-commit run --all-files # lint all |
| 166 | +pre-commit run --files path/to/File.vue # lint specific files |
| 167 | +``` |
| 168 | + |
| 169 | +Important: bare `pnpm jest` will NOT load `modulePaths` correctly — always go through `pnpm test` or pass `--config jest_config/jest.conf.js` explicitly. Always go through `pre-commit` — do not invoke ESLint / Black / Flake8 directly. |
| 170 | + |
| 171 | +## Docs Reference |
| 172 | + |
| 173 | +The Kolibri-dev docs site serves an LLM-friendly Markdown variant of every page — append `.md` to any URL below. The whole index is at https://kolibri-dev.readthedocs.io/en/latest/llms.txt. |
| 174 | + |
| 175 | +- Code quality: https://kolibri-dev.readthedocs.io/en/latest/code_quality.html.md |
| 176 | +- Testing (general): https://kolibri-dev.readthedocs.io/en/latest/testing.html.md |
| 177 | +- Frontend testing: https://kolibri-dev.readthedocs.io/en/latest/frontend_architecture/unit_testing.html.md |
| 178 | +- Backend testing: https://kolibri-dev.readthedocs.io/en/latest/backend_architecture/testing.html.md |
| 179 | +- i18n: https://kolibri-dev.readthedocs.io/en/latest/i18n.html.md |
| 180 | +- Frontend architecture: https://kolibri-dev.readthedocs.io/en/latest/frontend_architecture/index.html.md |
| 181 | +- Backend architecture: https://kolibri-dev.readthedocs.io/en/latest/backend_architecture/index.html.md |
| 182 | +- Development workflow: https://kolibri-dev.readthedocs.io/en/latest/development_workflow.html.md |
| 183 | + |
| 184 | +Local: `README.md`, `Makefile` (common commands), `docker-compose.yml` (service config). |
0 commit comments