Promethean Documentation System

A comprehensive fullstack documentation system for the Promethean Framework with asynchronous Ollama access, featuring AI-powered search, real-time updates, and modern web interface.

🚀 Features

Core Functionality

• Document Management: Create, edit, and organize documentation with metadata
• AI-Powered Search: Advanced search with semantic understanding and filtering
• Ollama Integration: Asynchronous job queue for AI model processing
• Real-time Updates: WebSocket-powered live updates and notifications
• User Management: Authentication, authorization, and role-based access control

Technical Features

• TypeScript Fullstack: End-to-end type safety
• Modern React Frontend: Ant Design components with React Query
• Express.js Backend: RESTful API with comprehensive middleware
• MongoDB Integration: Document storage with advanced indexing
• WebSocket Support: Real-time communication via Socket.IO
• Docker Ready: Containerized deployment with docker-compose

📋 Prerequisites

• Node.js 22+ (managed via Volta)
• pnpm 9.0.0+
• MongoDB 7.0+
• Ollama (for AI features)
• Docker & Docker Compose (optional, for containerized deployment)

🛠️ Installation

Local Development

1. Clone and navigate to the package:

   cd packages/docs-system

2. Install dependencies:

   pnpm install

3. Set up environment variables:

   cp .env.example .env
   # Edit .env with your configuration

4. Start MongoDB and Ollama:

   # Using Docker Compose (recommended)
   docker-compose up -d mongodb ollama
      
   # Or start services manually
   mongod
   ollama serve
   ollama pull llama2  # Pull default model

5. Build and run the application:

   # Build TypeScript
   pnpm run build
      
   # Start development server
   pnpm run dev:server
      
   # In another terminal, start frontend (if using separate dev server)
   pnpm run dev:frontend

Docker Deployment

1. Using Docker Compose (full stack):

   docker-compose up -d

2. Build and run container manually:

   docker build -t promethean-docs-system .
   docker run -p 3001:3001 -p 3000:3000 promethean-docs-system

🌐 Access Points

Once running, access the application at:

• Frontend: http://localhost:3000
• API Server: http://localhost:3001
• API Documentation: http://localhost:3001/api-docs
• Health Check: http://localhost:3001/health

📁 Project Structure

packages/docs-system/
├── src/
│   ├── server/              # Backend Express.js application
│   │   ├── database/        # MongoDB connection and models
│   │   ├── middleware/      # Express middleware (auth, rate limiting, etc.)
│   │   ├── routes/          # API route handlers
│   │   ├── websocket/       # Socket.IO WebSocket server
│   │   └── index.ts         # Server entry point
│   ├── frontend/            # React TypeScript application
│   │   ├── components/      # Reusable React components
│   │   ├── pages/           # Page components
│   │   ├── styles/          # CSS and styling
│   │   ├── index.tsx        # React app entry point
│   │   └── App.tsx          # Main app component
│   ├── shared/              # Shared utilities and types
│   │   └── index.ts         # Common functions and helpers
│   └── types/               # TypeScript type definitions
│       └── index.ts         # Core system types
├── dist/                    # Compiled JavaScript output
├── docker-compose.yml       # Development environment
├── Dockerfile              # Production container
├── package.json            # Dependencies and scripts
├── tsconfig.json           # TypeScript configuration
└── vite.config.ts          # Frontend build configuration

🔧 Configuration

Environment Variables

Key configuration options in .env:

# Server
NODE_ENV=development
PORT=3001
HOST=localhost

# Database
DATABASE_URL=mongodb://localhost:27017
DATABASE_NAME=promethean_docs

# Ollama AI
OLLAMA_ENDPOINT=http://localhost:11434
OLLAMA_DEFAULT_MODEL=llama2

# Security
JWT_SECRET=your-secret-key
BCRYPT_ROUNDS=12

# Logging
LOG_LEVEL=info
LOG_FORMAT=json

System Settings

The application includes a comprehensive settings interface accessible via the web UI at /settings. Configure:

• General: Site name, description, language, timezone
• Search: Fuzzy search, semantic search, result limits
• AI: Ollama models, token limits, caching
• Security: Rate limiting, audit logging, session timeout
• Performance: Caching, compression, upload limits

🔌 API Documentation

Authentication

All API endpoints (except /health and /api-docs) require JWT authentication:

# Login
POST /api/v1/auth/login
{
  "email": "[email protected]",
  "password": "password"
}

# Use token in subsequent requests
Authorization: Bearer <jwt-token>

Key Endpoints

• Documents: /api/v1/documents - CRUD operations for documentation
• Queries: /api/v1/queries - AI-powered search and analysis
• Ollama Jobs: /api/v1/ollama - Manage AI processing jobs
• Users: /api/v1/users - User management and profiles

WebSocket Events

Connect to WebSocket for real-time updates:

const socket = io('ws://localhost:3001', {
  auth: { token: 'your-jwt-token' }
});

// Subscribe to job updates
socket.emit('subscribe:jobs');

// Listen for updates
socket.on('job:update', (data) => {
  console.log('Job updated:', data);
});

🧪 Development

Available Scripts

# Build
pnpm run build              # Build TypeScript
pnpm run build:frontend     # Build frontend only

# Development
pnpm run dev                # Start both frontend and backend
pnpm run dev:server         # Start backend only
pnpm run dev:frontend       # Start frontend only

# Testing
pnpm run test               # Run tests
pnpm run test:watch         # Watch mode
pnpm run test:coverage      # With coverage

# Code Quality
pnpm run lint               # ESLint
pnpm run lint:fix           # Auto-fix linting
pnpm run typecheck          # TypeScript check

# Docker
pnpm run docker:build       # Build container
pnpm run docker:run         # Run container

Code Style

• TypeScript: Strict mode enabled
• ESLint: Configured for best practices
• Prettier: Code formatting
• Husky: Pre-commit hooks (if configured)

🚀 Deployment

Production Deployment

1. Environment Setup:

   export NODE_ENV=production
   export JWT_SECRET=your-production-secret
   # Set other production variables

2. Database Setup:

   # Ensure MongoDB is running with proper security
   # Create indexes for performance

3. Build and Deploy:

   pnpm run build
   docker-compose -f docker-compose.prod.yml up -d

Monitoring

• Health Checks: /health endpoint
• Logs: Structured JSON logging
• Metrics: Built-in performance monitoring
• Error Tracking: Comprehensive error handling

🔒 Security

Implemented Features

• JWT Authentication: Secure token-based auth
• Rate Limiting: Configurable request limits
• Input Validation: Zod schema validation
• CORS Protection: Configurable origin policies
• Helmet.js: Security headers
• Password Hashing: bcrypt with configurable rounds

Best Practices

• Use HTTPS in production
• Rotate JWT secrets regularly
• Implement proper database security
• Monitor and audit access logs
• Keep dependencies updated

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

📄 License

This project is part of the Promethean Framework and is licensed under the GPL-3.0 license.

🆘 Support

• Documentation: Check this README and inline code documentation
• API Docs: Visit /api-docs when running
• Issues: Report via GitHub issues
• Community: Join the Promethean Framework community

🔮 Roadmap

• [ ] Advanced AI model management
• [ ] Multi-language support
• [ ] Advanced analytics dashboard
• [ ] Plugin system for extensions
• [ ] Mobile app companion
• [ ] Advanced collaboration features
• [ ] Enterprise SSO integration
• [ ] Advanced search algorithms