docengine - Moses Yebei

The Problem

Collaborative document editing usually means signing up for a heavyweight SaaS product or wiring together half a dozen services. This repo is a self-contained, Dockerized alternative: a lightweight editor with import, sharing, and attachments that runs entirely on your own infrastructure.

What This Does

DocEngine is a full-stack document editor. The backend (backend/app/) is a FastAPI service with Postgres persistence, Alembic migrations, JWT auth, and role-based permissions. The frontend (frontend/src/) is a React 18 + TypeScript SPA using TipTap for rich-text editing. Documents autosave 800ms after typing stops, with conflict detection.

Import supports .txt, .md, and .docx (images/tables dropped, stated up front). Sharing grants viewer or editor roles by email. The repo includes a seed script (backend/app/seed.py) that creates four demo users with pre-populated documents.

How It Is Wired

Execution starts at backend/app/main.py for the API and frontend/src/main.tsx for the SPA. The frontend routes through frontend/src/api/client.ts (8 modules depend on it) to REST endpoints handled by routers in backend/app/routers/. Services in backend/app/services/ contain business logic — document_service.py and permission_service.py are the core. Repositories (backend/app/repositories/) abstract SQLAlchemy queries.

The module graph shows frontend/src/types/index.ts as the hub: 14 modules import it, so changes there ripple widely. frontend/src/pages/DocumentEditorPage.tsx has the highest cognitive load (10 imports, instability 0.91) — it's where editor state, autosave, and sharing converge. The graph is clean: 94 modules, 76 edges, zero circular dependencies.

The system touches Postgres (documents, users, shares, versions, attachments), the filesystem (storage/uploads/ for attachments), and the network (JWT auth, import file uploads).

How To Use It

git clone https://github.com/moses-y/docengine
cd docengine
cp .env.example .env
docker compose up --build

Open http://localhost:5173. Login with alice@ajaia.test / demo1234. The API container runs migrations and seeding automatically on startup.

Local dev without Docker: backend uses uvicorn app.main:app --reload from backend/; frontend uses npm run dev from frontend/. Tests: pytest -q in backend/ (integration tests self-skip without Docker), npm test in frontend/.

Real-World Use

A small team or internal tool needing document editing without external SaaS dependencies. The seeded users and permission matrix (404 for strangers, 403 for under-privileged viewers — tested exhaustively in tests/test_permissions.py) make it suitable as a starting point for a production internal knowledge base or report-generation tool.

Code Health & Issues

Static analysis found 9 findings (1 high, 8 medium):

High — deep nesting in backend/app/seed.py and backend/tests/test_sanitize.py (indentation depth 8). Flatten with guard clauses.
Medium — hub module frontend/src/types/index.ts (14 dependents). Keep stable.
Medium — duplicated code across backend/app/database.py, backend/app/models/ files. Extract shared helpers.
Medium — broad exception handling in database.py, security.py, and integration conftest.py. Catch specific exceptions.

SDLC gaps: no CI workflow, no LICENSE file (all rights reserved by default), and the backend Dockerfile runs as root with an unpinned python:3.12-slim base image. Dependencies are stale — 17 of 31 packages are multiple major versions behind (jsdom is 5 majors behind).

The Bottom Line

Solid, well-structured full-stack project with good test coverage and clean module boundaries. The gaps are operational — CI, licensing, container hardening — not architectural. Worth using as a reference for FastAPI + React patterns, or as a starting point for a self-hosted document tool if you add the missing SDLC plumbing.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

126 files

Python56
TSX22
TypeScript16
Markdown9
JSON5
YAML2

ReactDocker

Module dependencies

The 10 most depended-upon modules of 94, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_frontend_src_types_index["index"] n1_frontend_src_api_client["client"] n2_src_components_common_Button["Button"] n3_frontend_src_api_documents["documents"] n4_omponents_common_ErrorBanner["ErrorBanner"] n5_frontend_src_lib_constants["constants"] n6_rc_components_common_Spinner["Spinner"] n7_ontend_src_hooks_useAutosave["useAutosave"] n8_ponents_editor_SaveIndicator["SaveIndicator"] n9_rc_components_editor_Toolbar["Toolbar"] n1_frontend_src_api_client --> n5_frontend_src_lib_constants n1_frontend_src_api_client --> n0_frontend_src_types_index n3_frontend_src_api_documents --> n1_frontend_src_api_client n3_frontend_src_api_documents --> n0_frontend_src_types_index n8_ponents_editor_SaveIndicator --> n7_ontend_src_hooks_useAutosave n7_ontend_src_hooks_useAutosave --> n3_frontend_src_api_documents n7_ontend_src_hooks_useAutosave --> n1_frontend_src_api_client n7_ontend_src_hooks_useAutosave --> n5_frontend_src_lib_constants n7_ontend_src_hooks_useAutosave --> n0_frontend_src_types_index

Dependencies

17 of 31 declared dependencies are a major version behind. Resolved 31 of 31 against the registry.

Package	Declared	Latest	Behind
`jsdom`	^25.0.1	30.0.1	5 major
`vite`	^5.4.8	8.2.1	3 major
`argon2-cffi`	>=23.1	25.1.0	2 major
`structlog`	>=24.4	26.1.0	2 major
`@vitejs/plugin-react`	^4.3.2	6.0.5	2 major
`typescript`	^5.6.3	7.0.2	2 major
`vitest`	^2.1.2	4.1.10	2 major
`markdown-it-py`	>=3.0	4.2.0	1 major

Findings

MediumNo CI/CD pipeline detected - no automated build/test gate .github/ or CI config
MediumNo LICENSE file - unclear usage/redistribution rights root

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high3

medium3

Add a LICENSE; redistribution rights are undefinedhigh

no licence file at the repository root

Fix: Add MIT or Apache-2.0 at the repository root.

Add a workflow that builds and tests this repositoryhigh

94 source files, no CI configuration

Every change merges with nobody having run the build once, which across this estate is 499 repositories.

Fix: Add a workflow running the project build and test command on push and pull_request.

Add a build gate for the deployable artifacts herehigh3 occurrences

backend/Dockerfile

deployment artifacts with no workflow

Something in the repo is meant to reach a server and no automated step has ever validated it, which is the state of 125 repositories here.

Fix: Add a workflow that at least builds the image and validates the manifests.

Enable Dependabot or Renovatemedium

5 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

backend/Dockerfile

python:3.12-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Add a non-root USER to the imagemedium

backend/Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.