Everything you need
to know.

Overview

Cannelle is an open-core, self-hosted business lifecycle management platform designed for professional services companies — particularly agencies working with remote teams and contractors. It covers the full client relationship lifecycle from lead to invoice, with built-in collaboration tools for both internal staff and external contacts.

// key capabilities

Architecture

Cannelle is a monorepo built with npm workspaces and Turborepo. Business logic lives in @cannelle/core; both SvelteKit apps are thin presentation layers. Community is the internal staff application — the main platform used by your team to manage clients, projects, resources, and invoices. Atelier is a separate portal for external contacts (clients and resources) to exchange messages, upload files, and track their assignments.

cannelle-sveltekit/
├── packages/
│   ├── core/           @cannelle/core — Prisma, services, auth, email, storage, PDF, WebSocket, SSE
│   └── ui/             @cannelle/ui — shared Svelte components (workspaces, modals, pagination)
├── apps/
│   ├── community/      @cannelle/community — internal staff app (port 3000 / 5173 dev)
│   └── atelier/        @cannelle/atelier — external user portal (port 3001 / 5174 dev)
├── docker/             Dockerfile, docker-compose.yml, nginx, certbot scripts
├── turbo.json
└── .env.example

// design principles

// importing from @cannelle/core

import { getDb } from '@cannelle/core/db';
import { Permission } from '@cannelle/core/types';
import { createProject, getInvoice } from '@cannelle/core/services';
import { sendEmail } from '@cannelle/core/email';
import { getStorage } from '@cannelle/core/storage';
import { validateSession } from '@cannelle/core/auth';
import { validateExternalSession } from '@cannelle/core/auth/external';
import { broadcast } from '@cannelle/core/sse';

Tech Stack

Data Model

The Prisma schema defines 38 models. Every entity is scoped to a companyId. Multi-tenancy is supported but disabled by default via the CANNELLE_MULTITENANT environment variable.

// core entities

// key design patterns

Core Modules

@cannelle/core/services exports 100+ functions organized by domain. All business logic, validation, and database access lives here.

// utilities

Application Workflows

// sales pipeline

// project lifecycle

Also: DRAFT → CANCELLED at any point

// invoice lifecycle

// resource vetting

// integrations (webhooks)

Cannelle can push events to external systems via webhook endpoints. There are 16 automatic triggers across the quote, project, and invoice lifecycle — each delivering a structured JSON payload with the event name, timestamp, and the full entity at the time of the event.

// activity feed & followings

Cannelle has a built-in subscription model: users follow entities they care about — clients, quotes, projects, resources, or invoices — and receive a personalised activity feed showing everything that has changed on those entities. The feed is surfaced both on the dashboard and on a dedicated page. Step-by-step usage is covered in the User Guide.

// dashboard

A configurable two-column widget board. Visibility and order are saved per-user in localStorage. Widgets can be reordered by drag-and-drop.

Authentication & Authorization

// magic link flow (internal)

// permission model

Permissions are stored as a flat JSON map in user.settings:

Domains: clientssalesprojectssuppliersinvoicesreportssettings

// atelier — external user auth

Clients and resources accessing the Atelier portal use a separate, fully isolated authentication system (ExternalUser, ExternalSession, ExternalToken). First-time access is via an invitation link sent by an internal user. Subsequent logins use the same magic link flow. Sessions last 90 days.

// rate limiting

File Storage

Cannelle uses a storage adapter pattern that supports both local filesystem and AWS S3. Switching providers requires only a change to the STORAGE_PROVIDER environment variable.

// upload paths

{mount}/cannelle/uploads/{companyId}/
├── logo/                                       Company logo
├── documents/                                  Company documents
├── templates/                                  PDF templates
├── users/{userId}/avatars/                     User avatars
├── clients/{clientId}/{uuid}/                  Client files
├── suppliers/{supplierId}/{uuid}/             Resource files
├── projects/{projectId}/{uuid}/               Project files
├── projects/{projectId}/tasks/{taskId}/       Task files
├── documents/invoices/{invoiceId}/{uuid}/     Invoice files
└── resources/{workspaceId}/{uuid}/           Workspace files

When using S3, files are served via presigned download URLs (2-hour expiry) and uploaded via presigned upload URLs (5-minute expiry) for direct client-to-S3 uploads.

Email System

Emails are sent via SMTP using Nodemailer with Handlebars templates. SMTP is configured globally via environment variables.

// built-in templates

Beyond the system templates, companies can define their own pre-written email texts via the settings UI. All sent emails are logged in the Emails table.

Real-Time

Two complementary transports are used — WebSocket for the internal Community app, and Server-Sent Events (SSE) for the lighter-weight Atelier portal.

PDF Generation

PDFs are generated server-side using Puppeteer (headless Chromium) for invoices, project quotes, and resource assignments.

API Reference

All endpoints require a valid session cookie unless noted. The Community app and Atelier app each expose their own separate APIs.

// authentication

// clients

// projects & tasks

// resources

// invoices

// other community endpoints

// atelier api

Requires a valid atelier_session cookie.

Getting Started

// prerequisites

// local development

git clone https://github.com/cannelleio/community.git
cd cannelle-sveltekit

npm install

cp .env.example .env
# Edit .env with your database credentials and secrets

npm run db:generate   # generate Prisma client
npm run db:migrate    # run migrations (creates tables)

npm run dev
# Community app → http://localhost:5173
# Atelier portal → http://localhost:5174

// useful commands

Docker Deployment

The docker/ directory contains everything needed to build and deploy Cannelle. Two separate Docker images are built from a shared monorepo Dockerfile.

// compose stack

The default docker-compose.yml starts four services:

// building the images

Both images are built from the repository root using build arguments to select the app:

# Community
docker build \
  -f docker/Dockerfile \
  --build-arg APP_NAME=@cannelle/community \
  --build-arg APP_PATH=apps/community \
  --build-arg APP_PORT=3000 \
  -t your-repo/cannelle-community:latest \
  .

# Atelier
docker build \
  -f docker/Dockerfile \
  --build-arg APP_NAME=@cannelle/atelier \
  --build-arg APP_PATH=apps/atelier \
  --build-arg APP_PORT=3001 \
  -t your-repo/cannelle-atelier:latest \
  .

// starting the stack

cd docker
cp .env.example .env
# Set image names, database credentials, secrets, and BASE_URL
docker compose up -d

// nginx proxy with ssl

# One-time Let's Encrypt bootstrap
./init-letsencrypt.sh

# Subsequent starts
docker compose -f docker-compose.yml -f docker-compose.proxy.yml up -d

// data persistence

// recommendations

Configuration Reference

// generate secrets

openssl rand -hex 32   # JWT_SECRET
openssl rand -hex 16   # HASHID_SALT
openssl rand -hex 32   # ENCRYPTION_KEY
openssl rand -hex 16   # ENCRYPTION_SALT

// environment variables

Custom Task Types

Cannelle ships with four built-in task types — Basic, Copywriting, Interpreting, and Translation. You can add your own types without any schema changes — task data is stored as arbitrary JSON.

// registry architecture

apps/community/src/components/tasks/
├── _registry.ts              ← type → component mapping
├── generic/                  ← "Basic" task type
│   ├── TaskNew.svelte
│   ├── TaskEdit.svelte
│   ├── Settings.svelte
│   └── Pricing.svelte
├── copywriting/
├── interpreting/
├── translation/
└── TaskManager.svelte        ← resolves components from registry

// adding a custom type

cp -r apps/community/src/components/tasks/generic/ \
      apps/community/src/components/tasks/my-service/

import MyServiceTaskNew from './my-service/TaskNew.svelte';
import MyServiceTaskEdit from './my-service/TaskEdit.svelte';
import MyServiceSettings from './my-service/Settings.svelte';
import MyServicePricing from './my-service/Pricing.svelte';

// Add to the registry object:
'my-service': {
    components: {
        taskNew: MyServiceTaskNew,
        taskEdit: MyServiceTaskEdit,
        settings: MyServiceSettings,
        pricing: MyServicePricing
    },
    metadata: {
        label: 'My Service',
        title: 'My Custom Service',
        description: 'Shown on the settings page.',
        hasLanguages: false
    }
}

Development Setup

// setup

// code conventions