captify-core

A comprehensive shared library providing reusable UI/UX components, utilities, hooks, and services for Captify applications. Built with Next.js 16, React 19, TypeScript, and Tailwind CSS using shadcn/ui components.

Features

• Modern UI Components - Built on shadcn/ui with Radix UI primitives
• Authentication - NextAuth.js 5 integration with AWS Cognito
• AI/Chat Integration - AI SDK with multi-provider support (Bedrock, Anthropic, OpenAI)
• Feature-Based Architecture - Modular, domain-driven organization
• Type-Safe - Full TypeScript support with Zod validation
• Real-time Collaboration - Yjs integration for collaborative editing
• Dark Mode - Theme support with next-themes

Table of Contents

• Installation
• Quick Start
• Architecture
• Module Reference
• Import Patterns
• Development
• Scripts
• Contributing

Installation

npm install captify

Or using yarn:

yarn add captify

Or using pnpm:

pnpm add captify

Peer Dependencies

Ensure your project has these peer dependencies:

npm install next@^16.0.0 react@^19.0.0 react-dom@^19.0.0

Requirements

• Node.js >= 20.0.0

Quick Start

Importing from Feature Modules

The library uses a feature-based module structure. Import from specific module paths:

// Shell components (layouts, toolbars, sidebar)
import { ConsoleLayout } from 'captify/shell/components';
import { ThemeProvider } from 'captify/shell/theme-provider';

// Authentication
import { auth, signIn, signOut } from 'captify/auth';
import { AuthSessionProvider } from 'captify/auth/components';

// Chat components and services
import { ChatInterface, ChatMessages } from 'captify/chat/components';
import { useChatSession } from 'captify/chat/hooks';
import { ChatService } from 'captify/chat/services';

// Shared utilities and components
import { cn } from 'captify/shared/utilities/cn';
import { Button, Card, Dialog } from 'captify/shared/components';

// File management
import { FileUploader } from 'captify/files/components';
import { useFileUpload } from 'captify/files/hooks';

// User management
import { UserProfile } from 'captify/users/components';

Basic Layout Setup

import { ConsoleLayout } from 'captify/shell/components';
import { ThemeProvider } from 'captify/shell/theme-provider';
import { AuthSessionProvider } from 'captify/auth/components';

export default function RootLayout({ children }) {
  return (
    <AuthSessionProvider>
      <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
        <ConsoleLayout appName="My Application">
          {children}
        </ConsoleLayout>
      </ThemeProvider>
    </AuthSessionProvider>
  );
}

Architecture

Feature-Based Module Structure

The lib/ directory uses a domain-driven, feature-based organization. Each feature module contains:

lib/<feature>/
├── <feature>.interfaces.ts   # TypeScript interfaces
├── <feature>.schemas.ts      # Zod validation schemas
├── <feature>.constants.ts    # Constants and configuration
├── <feature>.utilities.ts    # Helper functions
├── <feature>.errors.ts       # Error classes
├── api/                      # API client and route handlers
├── components/               # React components
├── context/                  # React context providers
├── hooks/                    # Custom React hooks
└── services/                 # Business logic and integrations

Core Feature Modules

| Module | Description | |--------|-------------| | agents/ | AI agent components, interfaces, and chat functionality | | auth/ | NextAuth.js 5 + AWS Cognito authentication | | bookmarks/ | Bookmark management for services and resources | | breadcrumb/ | Navigation breadcrumb components | | chat/ | Chat interface, messaging, and AI conversation | | feedback/ | User feedback collection and management | | files/ | File management, upload, and S3 integration | | groups/ | User group management | | llm-providers/ | LLM provider configuration (Bedrock, Anthropic, OpenAI) | | ontology/ | Ontology/knowledge graph support | | shared/ | Shared utilities, UI components, providers | | shell/ | Application shell (layouts, toolbar, sidebar, theme) | | tables/ | Data table components and utilities | | users/ | User management and profiles |

Module Reference

Shell Module

Application shell components for layout and navigation:

// Components
import {
  ConsoleLayout,
  AppLauncher,
  AppSidebar,
  TopToolbar
} from 'captify/shell/components';

// Theme
import { ThemeProvider } from 'captify/shell/theme-provider';

// Hooks
import { useSidebar } from 'captify/shell/hooks';

// Types
import type { MenuItem, ServiceItem } from 'captify/shell/shell.interfaces';

Auth Module

Authentication with NextAuth.js 5 and AWS Cognito:

// Core auth
import { auth, signIn, signOut } from 'captify/auth';

// Components
import { AuthSessionProvider, LoginButton } from 'captify/auth/components';

// Hooks
import { useSession } from 'captify/auth/hooks';

// Services
import { CognitoService } from 'captify/auth/services';

// Actions
import { signOutAction } from 'captify/auth/actions';

Chat Module

AI-powered chat interface with multi-provider support:

// Components
import {
  ChatInterface,
  ChatMessages,
  ChatInput,
  ChatHistory,
  ChatModelSelector
} from 'captify/chat/components';

// Hooks
import { useChatSession, useChat } from 'captify/chat/hooks';

// Context
import { ChatProvider, useChatContext } from 'captify/chat/context';

// Services
import { ChatService } from 'captify/chat/services';

// Types
import type { ChatMessage, ChatSession } from 'captify/chat/chat.interfaces';
import { chatMessageSchema } from 'captify/chat/chat.schemas';

Files Module

File management with S3 integration:

// Components
import { FileUploader, FileList, FileViewer } from 'captify/files/components';

// Hooks
import { useFileUpload, useFiles } from 'captify/files/hooks';

// Services
import { FileService, S3Service } from 'captify/files/services';

// Types
import type { FileMetadata } from 'captify/files/files.interfaces';

Shared Module

Common utilities, UI components, and providers:

// UI Components (shadcn/ui)
import {
  Button,
  Card,
  Dialog,
  Input,
  Select,
  Tabs,
  Toast,
  Tooltip
} from 'captify/shared/components';

// Utilities
import { cn } from 'captify/shared/utilities/cn';
import { formatDate } from 'captify/shared/utilities/date-utilities';
import { invariant } from 'captify/shared/utilities/invariant';

// Providers
import { QueryProvider } from 'captify/shared/providers';

// Hooks
import { useMobile, useDebounce } from 'captify/shared/hooks';

LLM Providers Module

Multi-provider LLM configuration:

// Components
import { ModelSelector, ProviderConfig } from 'captify/llm-providers/components';

// Hooks
import { useModelSelection } from 'captify/llm-providers/hooks';

// Services
import { LLMProviderService } from 'captify/llm-providers/services';

// Types
import type { LLMProvider, ModelConfig } from 'captify/llm-providers/llm-providers.interfaces';

Import Patterns

Module-Level Imports (Recommended)

Import from the module's category exports:

import { ChatInterface } from 'captify/chat/components';
import { useChat } from 'captify/chat/hooks';
import { ChatService } from 'captify/chat/services';

Granular Imports

For maximum tree-shaking, import from specific files:

import { cn } from 'captify/shared/utilities/cn';
import { formatDate } from 'captify/shared/utilities/date-utilities';
import { invariant } from 'captify/shared/utilities/invariant';

Type Imports

Import interfaces and schemas directly:

import type { ChatMessage } from 'captify/chat/chat.interfaces';
import { chatMessageSchema } from 'captify/chat/chat.schemas';
import { CHAT_CONSTANTS } from 'captify/chat/chat.constants';

Development

Prerequisites

• Node.js >= 20.0.0
• npm/pnpm/yarn

Setup

1. Clone the repository
2. Install dependencies:

   npm install

3. Copy the environment template:

   cp .env.example .env

4. Configure your environment variables

Running the Test Application

The app/ directory contains a test application for developing and testing library components:

npm run dev

Open http://localhost:3000

Storybook

Interactive component documentation:

npm run storybook

Open http://localhost:6006

Scripts

# Development
npm run dev              # Start Next.js dev server with Turbopack (port 3000)
npm run storybook        # Start Storybook on port 6006

# Building
npm run build            # Build library (TypeScript to dist/)
npm run build:next       # Build Next.js app

# Validation
npm run validate         # Run lint + type-check
npm run lint             # Run ESLint
npm run lint:fix         # ESLint with auto-fix
npm run type-check       # TypeScript check without emit

# Formatting
npm run prettify         # Check Prettier formatting
npm run prettify:fix     # Auto-format with Prettier

# Testing
npm test                 # Run Playwright e2e tests
npm run test:ui          # Playwright UI mode
npm run test:headed      # Playwright headed mode
npm run test:debug       # Playwright debug mode
npm run test:unit        # Run Vitest unit tests

TypeScript Configuration

• tsconfig.json - Development config for Next.js
• tsconfig.build.json - Library build config (compiles lib/ to dist/)

Path Aliases

• @/* maps to project root
• captify/* maps to lib/*

Code Quality

ESLint Rules

• no-console: error - Use // eslint-disable-next-line no-console for intentional logs
• no-undef: error - All variables must be defined
• Unused variables with _ prefix are allowed
• lib/shared/components/ui/** is ignored (shadcn/ui components)

Pre-commit Hooks

Husky runs lint-staged on commit for:

• ESLint fixes
• Prettier formatting

AWS Services Integration

The library integrates with multiple AWS services:

• Cognito - User authentication and management
• S3 - File storage and presigned URLs
• DynamoDB - Database operations
• Bedrock - AI/LLM inference

AI SDK Integration

Multi-provider AI support via Vercel AI SDK:

• Amazon Bedrock - Claude, Titan models
• Anthropic - Direct Claude API
• OpenAI - GPT models

Contributing

1. Create a feature branch from dev
2. Make your changes following the feature-based module structure
3. Run npm run validate to ensure quality
4. Commit your changes (pre-commit hooks will run)
5. Submit a pull request to dev

License

Anautics Inc. All rights reserved.