Knowtis

AI-powered collaborative notes platform — your notes are your knowledge base

---

Table of Contents

• Overview
• Quick Start
• Project Structure
• Running the Project
• Available Scripts
• Architecture
• Development
• Documentation
• Contributing
• License

---

Overview

Knowtis is an AI-powered collaborative workspace that turns your notes into a knowledge base:

• 🤖 AI Assistant - Improve writing, fix spelling, summarize, translate, and expand content with inline AI actions
• 💬 AI Copilot - Conversational assistant that reads and edits your notes with approval (HITL), with per-conversation model selection and bring-your-own-key (BYOK) billing
• 🧠 Study Tools - Auto-generate flashcards, quizzes, summaries, and mind maps from your notes
• 🃏 Spaced Repetition - SM2 algorithm for optimal flashcard review scheduling
• 📝 Rich Text Editing - Tiptap/ProseMirror with slash commands, ghost text suggestions, and AI blocks
• 🔄 Real-time Collaboration - CRDT-based sync using Yjs with live presence and remote cursors
• 🎙️ Voice Notes - Record and transcribe voice notes with AI processing
• 🌐 Offline Support - IndexedDB persistence with optimistic local-first updates
• 🔐 Secure Authentication - JWT-based auth with HttpOnly cookie refresh tokens
• 🌍 Internationalization - Full i18n support (English and Spanish)
• 🔌 MCP Integration - Model Context Protocol server for AI assistant workflows
• 🛠️ Admin Backoffice - Ops surface for users, feature flags, runtime AI config, and AI metrics
• 🎨 Modern UI - Tailwind CSS 4 with dark mode, resizable panels, and responsive design

---

Quick Start

Prerequisites

Setup

git clone git@github.com:jovandyaz/knowtis_app.git
cd knowtis_app
pnpm setup       # installs deps, scaffolds .env files, starts Docker, pushes the schema
pnpm setup:agents # installs the project-scoped Claude Code plugins (optional)
pnpm dev:all     # starts the API + Notes + Backoffice

pnpm setup is idempotent — it never overwrites an existing .env. AI features (/api/ai/*) need an ANTHROPIC_API_KEY or OPENAI_API_KEY in apps/api/.env after the first run.

Design-system tokens are regenerated automatically before the app starts (the serve/build targets depend on design-system:build), so pnpm dev:all works on a fresh clone with no extra step.

To run apps individually instead:

pnpm dev             # Notes only (http://localhost:4200)
pnpm dev:backoffice  # Backoffice only (http://localhost:4400)
pnpm dev:api         # Backend only (http://localhost:3333)
pnpm dev:mcp         # MCP server only (http://localhost:3334)

New here? docs/LOCAL_SETUP.md is the full onboarding guide — verified boot sequence, how email verification works in local dev (the code is logged, not mailed), and how to connect an MCP client (Claude Desktop, Cursor, VS Code) to your local notes.

Access Points

---

Running the Project

Development Mode

Full Stack (Recommended)

# Start all services
pnpm docker:up      # Database + Redis
pnpm dev:all        # API + Notes + Backoffice

Frontend Only

pnpm dev

Note: When running frontend-only, collaboration will use WebRTC P2P mode (no backend required).

API Only

pnpm docker:up
pnpm dev:api

Production Build

# Build all projects
pnpm build      # Frontend → dist/apps/notes
pnpm build:api  # Backend → dist/apps/api

# Run production API
node dist/apps/api/main.js

# Preview production frontend
pnpm preview

Running Tests

pnpm test              # Run all tests
pnpm test:run          # Run tests once (no watch)
pnpm test:coverage     # Run with coverage report
nx test notes          # Test specific project
nx test api            # Test API project

---

Available Scripts

Development

Build & Preview

Testing & Quality

Database

Infrastructure

Nx Workspace

Makefile (Alternative)

For convenience, all commands are also available via make:

# Show all available commands
make help

# Quick workflows
make setup      # Full setup: install, docker, db
make start      # Start DB + all apps
make fresh      # Clean install from scratch
make ci         # Run full CI pipeline locally

# Common commands
make dev            # Start Notes frontend
make dev-api        # Start backend
make dev-backoffice # Start Backoffice frontend
make dev-all        # Start everything
make test           # Run tests
make lint           # Lint code
make build          # Build for production

Run make help to see all available targets with descriptions.

---

Architecture

Tech Stack

Dependency Flow

The workspace follows a unidirectional dependency flow:

graph TD
    subgraph Apps
        Notes[apps/notes]
        Backoffice[apps/backoffice]
        API[apps/api]
    end

    subgraph Libs
        ApiClient[libs/api-client]
        DataAccess[libs/data-access]
        Authorization[libs/authorization]
    end

    subgraph SharedPackages
        DesignSystem[packages/design-system]
        Shared[packages/shared]
    end

    Notes --> ApiClient
    Notes --> DataAccess
    Notes --> DesignSystem
    Backoffice --> DataAccess
    Backoffice --> DesignSystem
    ApiClient --> Shared
    DataAccess --> ApiClient
    DataAccess --> Shared
    DesignSystem --> Shared

    subgraph Packages
        Email[packages/email]
        EmailNestjs[packages/email-nestjs]
        Auth[packages/auth]
        AuthNestjs[packages/auth-nestjs]
    end

    API --> EmailNestjs
    API --> AuthNestjs
    EmailNestjs --> Email
    EmailNestjs --> AuthNestjs
    AuthNestjs --> Auth

Key Design Principles

• SOLID Principles - Clean, maintainable architecture
• Domain-Driven Design - Clear separation of concerns
• Type Safety - Strict TypeScript throughout
• Composition over Inheritance - Flexible component design

For detailed architecture documentation, see docs/ARCHITECTURE.md.

---

Development

Environment Variables

API (apps/api/.env)

# Database
DATABASE_URL=postgresql://knowtis:knowtis_dev@localhost:5432/knowtis

# Authentication
JWT_SECRET=your-jwt-secret-key
JWT_REFRESH_SECRET=your-refresh-secret-key
JWT_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=7d

# Server
PORT=3333
NODE_ENV=development
FRONTEND_URL=http://localhost:4200

Notes App (apps/notes/.env)

# API Configuration
VITE_API_URL=http://localhost:3333/api/v1
VITE_WS_URL=http://localhost:3333

# Collaboration Mode: 'webrtc' | 'websocket' | 'hybrid'
VITE_COLLABORATION_MODE=websocket

Code Quality

This project uses:

• ESLint - Code linting with modern flat config
• Prettier - Code formatting
• Lefthook - Git hooks (pre-commit, pre-push, commit-msg)

IDE Setup

Recommended VS Code extensions:

• ESLint
• Prettier
• Tailwind CSS IntelliSense
• Nx Console

---

Documentation

---

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on how to get started.

---

License

Licensed under the MIT License.

---

Built with ❤️ using Nx, React, and NestJS