This is the first MVP of a simple personal knowledge assistant Project for playing with ChromaDB and LangChain. This project is build with FastAPI and React, and AI technologies like LangGraph, Llama 3.1, and pgvector.

• tech stack: LangGraph + FastAPI + React + PostgreSQL/Redis + Llama 3.1 a modern, scalable combination
• Cost-effective design: Open-source components, avoiding API fees
• RAG implementation: Smart use of pgvector for semantic search over personal notes

1. Docker-First Development - Everything containerized
2. Clean Code Architecture - Proper separation of concerns
3. Type Safety - Full TypeScript + Pydantic coverage
4. Error Handling - Custom exceptions and graceful failures
5. Configuration Management - Environment-based settings
6. Health Checks - Monitoring and observability
7. Security Best Practices - Non-root containers, CORS, validation

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Backend       │    │   AI Services   │
│   React/TS      │◄──►│   FastAPI       │◄──►│   Ollama/Chroma │
│   + Zustand     │    │   + SQLAlchemy  │    │   + Embeddings  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                        │                        │
         ▼                        ▼                        ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   React Query   │    │   PostgreSQL    │    │   Vector Store  │
│   + React Hook  │    │   + Redis       │    │   (ChromaDB)    │
│   Form          │    │   + Alembic     │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

• React 18 - Latest React with concurrent features
• TypeScript 5 - Strict type checking
• Vite - Fast build tooling
• Tailwind CSS - Utility-first styling
• Zustand - Lightweight state management
• React Query - Server state management
• React Hook Form - Form handling
• Vitest - Testing framework

• FastAPI - Modern Python web framework
• SQLAlchemy 2.0 - Modern ORM with async support
• Pydantic v2 - Data validation and serialization
• Alembic - Database migrations
• PostgreSQL - Primary database
• Redis - Caching and sessions
• Pytest - Testing framework
• ChromaDB - Vector database

• Ollama - Local LLM serving
• sentence-transformers - Text embeddings
• Langchain - LLM integration framework

• Docker - Containerization
• Docker Compose - Local development
• pytest - Backend testing
• Vitest - Frontend testing
• GitHub Actions - CI/CD
• Pre-commit - Code quality hooks

• Node.js 18+
• Python 3.11+
• Docker & Docker Compose
• Git

git clone <repo-url>
cd personal-knowledge-assistant-mvp
cp .env.example .env

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Access the app
open http://localhost:3000

# Backend
cd backend
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload

# Frontend (new terminal)
cd frontend
npm install
npm run dev

cd backend
pytest -v --cov=app --cov-report=html

cd frontend
npm run test
npm run test:coverage

npm run test:e2e

mvp/
├── backend/                 # FastAPI backend
│   ├── app/
│   │   ├── api/            # API routes
│   │   ├── core/           # Core configuration
│   │   ├── models/         # Database models
│   │   ├── schemas/        # Pydantic schemas
│   │   ├── services/       # Business logic
│   │   └── tests/          # Backend tests
│   ├── alembic/            # Database migrations
│   └── requirements.txt
├── frontend/               # React frontend
│   ├── src/
│   │   ├── components/     # React components
│   │   ├── hooks/          # Custom hooks
│   │   ├── services/       # API services
│   │   ├── stores/         # Zustand stores
│   │   ├── types/          # TypeScript types
│   │   └── utils/          # Utility functions
│   └── package.json
├── docker-compose.yml      # Local development setup
├── .github/workflows/      # CI/CD pipelines
└── README.md

• Domain-driven design with clear boundaries
• Dependency injection for testability
• Repository pattern for data access
• Service layer for business logic

• 100% TypeScript coverage in frontend
• Pydantic models for API validation
• SQLAlchemy models with type hints
• API contract validation

• Unit tests for business logic
• Integration tests for API endpoints
• Component tests for React components
• E2E tests for critical user flows

• React Query for efficient data fetching
• Vector search with ChromaDB
• Database indexing for fast queries
• Redis caching for session management

• JWT authentication with refresh tokens
• Input validation with Pydantic
• SQL injection protection via ORM
• CORS configuration for API security

• Hot reload in development
• Type checking in CI/CD
• Code formatting with Prettier/Black
• Pre-commit hooks for code quality

• Responsive design - Mobile-first approach
• Real-time updates - WebSocket integration
• Loading states - Skeleton screens and spinners
• Error handling - User-friendly error messages
• Accessibility - ARIA labels and keyboard navigation

• Performance - Async support and high throughput
• Developer Experience - Automatic API documentation
• Type Safety - Pydantic integration
• Modern Python - Latest language features

• Caching - Intelligent data caching
• Background Updates - Automatic refetching
• Optimistic Updates - Better UX
• Error Handling - Comprehensive error states

• Simplicity - Easy to set up and use
• Performance - Fast vector similarity search
• Python Integration - Native Python support
• Local Development - No external dependencies

# Build production images
docker-compose -f docker-compose.prod.yml build

# Deploy to staging
docker-compose -f docker-compose.prod.yml up -d

# Health check
curl http://localhost:8000/health

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/pka
REDIS_URL=redis://localhost:6379

# Security
SECRET_KEY=your-secret-key
ACCESS_TOKEN_EXPIRE_MINUTES=30

# AI Services
OLLAMA_BASE_URL=http://localhost:11434
EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2

• Backend Response Time - < 100ms for most endpoints
• Frontend Bundle Size - < 500KB gzipped
• Test Coverage - > 90% for critical paths
• Type Coverage - 100% TypeScript strict mode

• ESLint - JavaScript/TypeScript linting
• Prettier - Code formatting
• Black - Python code formatting
• mypy - Python type checking
• Husky - Git hooks for quality gates

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

• FastAPI - For the excellent web framework
• React Team - For the amazing frontend library
• Ollama - For local LLM serving
• ChromaDB - For vector database capabilities