docling-studio/docs/architecture/coding-standards.md

Coding Standards

Conventions for writing consistent, readable code across the Docling Studio codebase.

Python (Backend — document-parser/)

Tooling

Tool	Purpose	Config
Ruff	Linting + formatting	ruff.toml / pyproject.toml
pytest	Testing	pytest.ini / pyproject.toml
mypy (optional)	Type checking	—

Naming

Element	Convention	Example
Modules	snake_case	analysis_repo.py
Classes	PascalCase	AnalysisJob, DocumentConverter
Functions / methods	snake_case	create_analysis()
Constants	UPPER_SNAKE_CASE	MAX_CONCURRENT_ANALYSES
Private	_leading_underscore	_build_converter()

Style Rules

• Max function length: 30 lines (soft limit — justify longer ones)
• Max file length: 300 lines (split into modules if exceeded)
• Imports: standard library → third-party → local, separated by blank lines
• Type hints on all public functions
• Docstrings only on non-obvious public APIs (don't state the obvious)
• No # type: ignore without a comment explaining why

Architecture Rules

• Domain layer (domain/): zero imports from api/, persistence/, infra/
• Persistence layer (persistence/): only imports from domain/
• API layer (api/): never imports from persistence/ directly — goes through services/
• Services (services/): orchestrate, don't implement — delegate to domain and infra

TypeScript / Vue (Frontend — frontend/src/)

Tooling

Tool	Purpose	Config
ESLint	Linting	.eslintrc.*
Prettier	Formatting	.prettierrc
vue-tsc	Type checking	tsconfig.json
Vitest	Testing	vitest.config.ts

Naming

Element	Convention	Example
Components	PascalCase.vue	BboxOverlay.vue
Composables	useCamelCase.ts	usePagination.ts
Stores	camelCase.ts	analysisStore.ts
Types / Interfaces	PascalCase	AnalysisJob, BboxRect
Constants	UPPER_SNAKE_CASE	DEFAULT_PAGE_SIZE
CSS classes	kebab-case	.bbox-overlay
data-e2e attributes	kebab-case	data-e2e="upload-zone"

Style Rules

• Composition API only (<script setup lang="ts">) — no Options API
• One component per file
• Props defined with defineProps<T>() (type-based, not runtime)
• Emits defined with defineEmits<T>()
• Pinia stores: one per feature, in the feature directory
• No global state outside Pinia
• API calls only in api.ts files (never in components or stores directly)

API Contract

• Frontend sends/receives camelCase (Pydantic alias_generator)
• Backend uses snake_case internally
• pages_json is an exception — contains raw snake_case from dataclasses.asdict()

Karate (E2E — e2e/)

See e2e/CONVENTIONS.md for detailed rules.

Key points:

• Use data-e2e selectors, never CSS classes
• Use retry()/waitFor(), never Thread.sleep() or delay()
• Setup via API, verify via UI, cleanup via API
• Tag tests: @critical, @ui, @smoke, @regression, @e2e