# Dorfteich

Dorfteich is an open-source wiki system built around **ponds** (German:
_Teiche_) — self-contained wiki spaces that people and teams organize freely
with hierarchical labels, directories, and Obsidian-style page relations.
Pages are edited in a collaborative WYSIWYG editor with live cursors and
offline support.

- Project site: <https://dorfteich.cloud>
- Public flagship instance: <https://dorfteich.online>
- License: [MIT](LICENSE)

## Key features

- **Real-time collaboration** — multiple people edit the same page
  simultaneously; everyone sees the other participants' cursors and input
  live. Offline edits merge conflict-free on reconnect (CRDT-based).
- **Ponds** — isolated wiki spaces with their own members, permissions,
  fonts, and page organization. Every registered person gets a personal pond.
- **Flexible organization** — hierarchical labels, free page ordering,
  `[[wikilinks]]` with backlinks. A classic page tree is possible but never
  enforced.
- **Fine-grained permissions** — roles (Site Admin, Pond Admin, Editor,
  Reader, Public) can be granted per pond, per label, or per page; the most
  specific setting wins.
- **Import & export** — Markdown as the primary exchange format, plus
  best-effort structural import from Word/OpenOffice and export to
  Word/OpenOffice/PDF.
- **Plugins** — sandboxed extensions (custom blocks, styles, page tools)
  installable at runtime without redeploying the instance.
- **Self-hosting first** — a single `docker compose up` plus a guided
  first-run setup wizard yields a working instance. Start here:
  [`docs/self-hosting/README.md`](docs/self-hosting/README.md).

## Repository layout

| Path                 | Contents                                                                                                                     |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `docs/architecture/` | Architecture documentation: ADRs, data model, permission model, collaboration and plugin concepts, deployment and operations |
| `docs/self-hosting/` | Install, update, backup, and troubleshooting guide for running your own instance                                             |
| `apps/`              | Application packages (web frontend, API server, collaboration server) — created as implementation proceeds                   |
| `packages/`          | Shared packages (types, permission logic, plugin SDK)                                                                        |
| `deploy/`            | Docker Compose stacks and deployment tooling                                                                                 |

## Development

Requirements: Node.js ≥ 22 and [pnpm](https://pnpm.io) (`npm install -g pnpm`).

```sh
pnpm install        # install all workspace dependencies
pnpm lint           # ESLint + Prettier check across the repo
pnpm typecheck      # TypeScript --noEmit in every package
pnpm test           # Vitest in every package
pnpm build          # build every package (dependency order)
```

The workspace packages live under `apps/` (web, api, collab) and
`packages/` (shared). Shared logic goes into `packages/shared` and is
imported as `@dorfteich/shared` — never copy code between apps.

## Status

The project is in the architecture and backlog phase. Implementation stories
are tracked as issues in this repository. Start reading at
[`docs/architecture/README.md`](docs/architecture/README.md).

## Contributing

Code, comments, and documentation are written in English. Write clear code
that humans can follow easily; when in doubt, prefer readability over
cleverness. All contributions are accepted under the MIT license.