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
• 🎨 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 dev:all     # starts the API + frontend

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.

To run apps individually instead:

pnpm dev      # Frontend only (http://localhost:4200)
pnpm dev:api  # Backend only (http://localhost:3333)

Access Points

Running the Project

Development Mode

Full Stack (Recommended)

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

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 frontend
make dev-api    # Start backend
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]
        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
    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