Build production-ready DocuLens portfolio showcase

.dockerignore

@@ -0,0 +1,18 @@
+.git
+.github
+.env
+.env.*
+!.env.example
+!.env.showcase.example
+.venv
+.venv312
+.pytest_cache
+.ruff_cache
+.coverage
+**/__pycache__
+**/*.py[cod]
+frontend/node_modules
+frontend/dist
+data/ingestion
+*.png
+*.log

.env.example

@@ -0,0 +1,28 @@
+# Runtime
+DOCULENS_ENVIRONMENT=development
+DOCULENS_LOG_LEVEL=INFO
+DOCULENS_CORS_ORIGINS=["http://localhost:5173"]
+DOCULENS_INITIALIZE_DATABASE=true
+DOCULENS_SEED_DEMO_USERS=false
+DOCULENS_SEED_DEMO_WORKSPACE=false
+DOCULENS_SHOWCASE_READ_ONLY=false
+DOCULENS_AUTH_SECRET=replace-with-a-long-random-value
+DOCULENS_API_KEY=
+
+# AI providers
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+OPEN_ROUTER_API_KEY=
+DOCULENS_PROVIDER_TIMEOUT_SECONDS=30
+DOCULENS_CHUNK_MAX_TOKENS=800
+DOCULENS_EMBEDDING_BATCH_SIZE=64
+DOCULENS_EMBEDDING_CACHE_SIZE=1024
+
+# Infrastructure
+PROJECT_NAME=doculens
+DATABASE_HOST=doculens_database
+DATABASE_PORT=5432
+DATABASE_NAME=doculens
+DATABASE_USER=postgres
+DATABASE_PASSWORD=doculens-local-only
+REDIS_URL=redis://doculens_redis:6379/0

.env.showcase.example

@@ -0,0 +1,29 @@
+# Copy to .env.showcase and replace every value marked "replace-me".
+PROJECT_NAME=doculens_showcase
+CADDY_DOMAIN=demo.example.com
+
+# Public showcase behavior
+DOCULENS_ENVIRONMENT=production
+DOCULENS_LOG_LEVEL=INFO
+DOCULENS_CORS_ORIGINS=["https://demo.example.com"]
+DOCULENS_RUN_MIGRATIONS=true
+DOCULENS_INITIALIZE_DATABASE=true
+DOCULENS_SEED_DEMO_USERS=false
+DOCULENS_SEED_DEMO_WORKSPACE=true
+DOCULENS_SHOWCASE_READ_ONLY=true
+DOCULENS_AUTH_SECRET=replace-me-with-openssl-rand-hex-32
+DOCULENS_API_KEY=
+
+# No provider call is reachable while showcase mode is enabled. These values
+# only let provider clients initialize during creation of the vector table.
+OPENAI_API_KEY=showcase-no-provider-calls
+ANTHROPIC_API_KEY=showcase-no-provider-calls
+OPEN_ROUTER_API_KEY=showcase-no-provider-calls
+
+# Private Compose network
+DATABASE_HOST=database
+DATABASE_PORT=5432
+DATABASE_NAME=doculens
+DATABASE_USER=postgres
+DATABASE_PASSWORD=replace-me-with-a-long-random-password
+REDIS_URL=redis://redis:6379/0

.github/workflows/backend-ci.yml

@@ -1,4 +1,4 @@
-name: Backend CI
+name: Quality
 
 on:
   push:
@@ -23,11 +23,40 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: "3.11"
+          cache: pip
 
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -r app/requirements.txt
+          pip install -e '.[dev]'
 
-      - name: Run tests
-        run: pytest
+      - name: Lint
+        run: ruff check .
+
+      - name: Type-check
+        run: pyright
+
+      - name: Run tests with coverage
+        run: pytest --cov=app --cov-report=term-missing
+
+  frontend:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install dependencies
+        run: npm --prefix frontend ci
+
+      - name: Lint
+        run: npm --prefix frontend run lint
+
+      - name: Build and type-check
+        run: npm --prefix frontend run build

.gitignore

@@ -16,6 +16,8 @@ eggs/
 .eggs/
 lib/
 lib64/
+!frontend/src/lib/
+!frontend/src/lib/**
 parts/
 sdist/
 var/
@@ -58,7 +60,7 @@ target/
 
 # DotEnv configuration
 .env
-.env.example
+!.env.example
 
 # Database
 *.db
@@ -89,9 +91,7 @@ target/
 
 # Virtual environment
 .venv/
-
-# docs
-/docs/
+.venv312/
 
 # Local ingestion uploads
 data/ingestion/

.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.3
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-added-large-files
+        args: [--maxkb=2000]
+      - id: detect-private-key

Makefile

@@ -0,0 +1,49 @@
+SHELL := /bin/bash
+.DEFAULT_GOAL := help
+
+.PHONY: help install dev up down showcase-up showcase-down showcase-logs test lint format typecheck check sample
+
+help: ## Show available commands
+	@awk 'BEGIN {FS = ":.*## "; printf "DocuLens developer commands\n\n"} /^[a-zA-Z_-]+:.*## / {printf "  %-12s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+install: ## Install backend and frontend development dependencies
+	python3 -m pip install -e '.[dev]'
+	npm --prefix frontend ci
+
+dev: ## Run API with hot reload
+	uvicorn app.main:app --reload --port 8080
+
+up: ## Start the complete Docker development stack
+	docker compose --env-file .env -f docker/docker-compose.yml up --build -d
+
+down: ## Stop the Docker development stack
+	docker compose --env-file .env -f docker/docker-compose.yml down
+
+showcase-up: ## Build and start the read-only portfolio showcase
+	docker compose --env-file .env.showcase -f docker/docker-compose.showcase.yml up --build -d
+
+showcase-down: ## Stop the read-only portfolio showcase
+	docker compose --env-file .env.showcase -f docker/docker-compose.showcase.yml down
+
+showcase-logs: ## Follow portfolio showcase logs
+	docker compose --env-file .env.showcase -f docker/docker-compose.showcase.yml logs -f --tail=200
+
+test: ## Run backend tests
+	pytest
+
+lint: ## Run backend and frontend lint checks
+	ruff check .
+	npm --prefix frontend run lint
+
+format: ## Format backend code
+	ruff format .
+	ruff check --fix .
+
+typecheck: ## Type-check backend and build/type-check frontend
+	pyright
+	npm --prefix frontend run build
+
+check: lint typecheck test ## Run the full local quality gate
+
+sample: ## Submit the sample search event to a running API
+	python3 requests/send_event.py requests/events/search_query.json