Refactor/python package and website deployment#33
Merged
simonweigold merged 83 commits intoApr 3, 2026
Conversation
… and adjust LLM tool tests.
…cation hooks, and adding new fonts and architecture documentation.
Research complete for Phase 01: Foundation covering: - Just task runner patterns and configuration - Ruff/mypy/pytest tooling setup - Dev container architecture (Docker Compose + PostgreSQL) - VS Code settings and extensions - Documentation standards (Keep a Changelog, Contributor Covenant) - Common pitfalls for Python/Node monorepos Addresses requirements: DOCS-01 through DOCS-06, TOOL-01 through TOOL-04, TOOL-06 through TOOL-08 Refs: CONTEXT.md decisions D-01 through D-07
- Add Ruff configuration to packages/clerk/pyproject.toml - Target Python 3.13 with 100-character line length - Enable rules: E, F, I, N, W (pycodestyle, Pyflakes, isort, pep8-naming) - Use Google-style docstring convention - Configure double quotes and spaces for formatting
- Add MIT License with OpenClerk Contributors copyright - Add CHANGELOG.md following Keep a Changelog 1.1.0 format - Add Contributor Covenant Code of Conduct v2.1 Addresses requirements: DOCS-05, DOCS-06
- Add pytest configuration with async mode and coverage reporting - Set coverage threshold to 80% with branch coverage - Add mypy strict mode configuration for Python 3.13 - Enable warn_return_any, warn_unused_configs, ignore_missing_imports
- Add setup command for full environment initialization - Add test command with pytest and coverage - Add lint command with Ruff and mypy - Add format command with Ruff formatter - Add dev command to start both backend and frontend - Add dev-backend and dev-frontend for individual services - Add clean command to remove build artifacts
- Add docs/README.md as main documentation entry point - Add docs/contributing/setup.md with platform-specific instructions - Add CONTRIBUTING.md with quick start and dev workflow - Create docs/user-guide/ and docs/integration/ directories Addresses requirements: DOCS-02, DOCS-03, DOCS-04
- Add SUMMARY.md with execution details and verification results - Update STATE.md with plan 02 completion - Update ROADMAP.md progress for phase 1 - Mark TOOL-01, TOOL-02, TOOL-03, TOOL-04, TOOL-06 as complete
- Rewrite README to be concise (48 lines, under 60 limit) - Add clear value proposition with quickstart - Include PyPI and License badges - Add installation (pip and source) and usage sections - Link to CONTRIBUTING.md for development setup Addresses requirements: DOCS-01, DOCS-02, DOCS-03
- Create SUMMARY.md with execution results - Update STATE.md with progress and metrics - Update ROADMAP.md with plan progress - Mark requirements DOCS-01 through DOCS-06 complete Plan 01-01 completed successfully.
- Add Dockerfile with Python 3.13, Node.js 20, UV, and Just - Add docker-compose.yml with PostgreSQL 15 service - Add devcontainer.json with postCreateCommand: just setup - Forward ports 3000 (frontend), 8000 (backend), 5432 (database) - Configure VS Code extensions in dev container
- Add extensions.json with Python, Ruff, ESLint, Tailwind, Prettier - Add settings.json with format-on-save configuration - Configure Ruff as default Python formatter - Configure Prettier for TypeScript/JavaScript - Add file exclusions for cache and build directories
- Add 01-03-SUMMARY.md with execution summary - Update STATE.md: advance to plan 3 of 3 completed - Update ROADMAP.md: mark Phase 1 as complete (3/3 plans) - Document all 5 created files and 2 commits
- Add .pre-commit-config.yaml with Ruff v0.6.0 and mypy v1.10.0 - Hooks configured: ruff (with --fix), ruff-format, mypy - Versions match pyproject.toml dev dependencies
- Create structured YAML form for bug reports - Include fields for description, reproduction, expected/actual behavior - Add environment input and optional additional context - Set 'bug' label for automatic categorization
- Add Pre-commit Hooks section after dev container setup - Document installation via 'uv pip install pre-commit' - Include hook installation and optional all-files run - Mention Ruff and mypy in the description
- Create structured YAML form for feature requests - Include fields for description, problem/use case, proposed solution - Add optional fields for alternatives and additional context - Set 'enhancement' label for automatic categorization
- Create root-level package.json for mono-repo workspace - Add dev script using concurrently to run backend and frontend - Backend runs via 'cd packages/clerk && uv run clerk web --port 8000' - Frontend runs via 'cd apps/website && npm run dev' - Use blue/green colors and API/UI prefixes for clear output - Add convenience scripts: setup, build, lint - Add concurrently ^8.2.2 as devDependency
- Quick start section with prerequisites - Architecture overview with data flow diagram - Configuration guide referencing .env file - Data persistence and backup procedures - Updating and troubleshooting sections - Advanced options for scaling and networking
- Add license-files field referencing LICENSE file per PEP 639 - Package name remains 'openclerk' per D-01 - Classifiers already include Development Status, Topic tags - Project URLs defined (Homepage, Docs, Repo, Issues) - Build system configured with hatchling PyPI metadata now complete for publishing.
- Multi-stage build with node:20-alpine builder stage - Production stage uses nginx:alpine for serving static files - Copy built dist/ assets to nginx html directory - Reference nginx.conf for SPA routing configuration - Expose port 80 for web traffic
- Serve static frontend files with SPA routing (try_files fallback) - Proxy /api/* requests to backend:8000 service - Add gzip compression for better performance - Include security headers (X-Frame-Options, X-Content-Type-Options, etc.) - Configure caching for static assets (1 year expiry)
- Add SECRET_KEY for application security - Add LOG_LEVEL for configurable logging - Add VITE_API_URL for frontend build-time variables - Add SUPABASE_KEY and SUPABASE_SERVICE_KEY per plan spec - Reorganize variables by category with clear required/optional markers - Include quick start instructions for new users - Maintain compatibility with existing CLERK_SESSION_SECRET
- Multi-container architecture with db, backend, and frontend services - PostgreSQL 16-alpine with health checks and persistent volume - Backend builds from root context using packages/clerk/Dockerfile - Frontend builds from apps/website context with nginx - Service dependencies with health conditions (backend waits for db) - env_file mounting for environment configuration (per D-04) - Named volume postgres_data for database persistence - Custom bridge network for service communication
- Complete documentation of all environment variables - Separate Required vs Optional sections - Security considerations and best practices - Quick reference table with all variables - Example production .env configuration - Supabase integration variables
- Document all 4 tasks completed - List artifacts delivered (setup.sh, package.json, pyproject.toml, .env.example) - Verify SETUP-01 and SETUP-03 requirements satisfied - Record commit hashes and verification results - Self-check passed: all files and commits verified
- HTTPS setup with nginx, Traefik, and Cloudflare options - Database security and backup procedures - Application security hardening - Horizontal scaling and connection pooling - Monitoring with health checks and metrics - Zero-downtime deployment strategies - Resource planning and PostgreSQL tuning - Production deployment checklist - Environment file security (chmod 600)
- Add SUMMARY.md with execution details, commits, and verification - Update STATE.md with plan progress (2 of 3) and key decisions - Update ROADMAP.md progress table for Phase 4 - Mark DEPLOY-01 requirement as complete - Record performance metrics (12min, 4 tasks, 4 files) Self-check: All 4 files created and committed successfully
- Add 'deployment' to DIR_NAMES mapping - Position Deployment after Integration in DIR_ORDER - Enables sidebar navigation for deployment documentation
- Add SUMMARY.md with execution results and verification - Update STATE.md with plan completion (3/3 plans complete) - Update ROADMAP.md progress for Phase 04 - Mark DEPLOY-02 and DEPLOY-03 requirements complete Phase 04 (distribution) is now 100% complete with all 3 plans: - 04-01: Environment setup and Docker - 04-02: Docker Compose and PyPI - 04-03: Deployment documentation
…handling in API routes
- Simplified selectinload options in ReasoningKitRepository. - Consolidated search condition logic in ReasoningKitRepository. - Streamlined SQLAlchemy queries for better clarity. - Enhanced async function signatures for consistency. - Improved error messages for clarity in load_reasoning_kit_from_db. - Cleaned up formatting and spacing across multiple files for better readability. - Updated test files to follow consistent formatting and structure.
simonweigold
commented
Apr 3, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces a comprehensive developer experience (DX) overhaul to the project, focusing on onboarding, contribution workflows, and environment setup. The changes automate and document the development environment using dev containers and Docker Compose, add clear configuration and onboarding documentation, and establish robust GitHub workflows and templates for issues and pull requests. The
.env.exampleis significantly improved for clarity and ease of use, and a planning document is added to clarify project scope and evolution.Development Environment & Tooling
.devcontainersupport with a customDockerfile,docker-compose.yml, anddevcontainer.jsonto enable zero-setup onboarding via GitHub Codespaces or local dev containers. This includes Python 3.13, Node.js 20, UV, Just, and a PostgreSQL database service. [1] [2] [3].env.examplewith clearer required/optional variable sections, usage notes, and quick start instructions, making local and database-backed setups much easier for new contributors.Project Documentation & Planning
.planning/PROJECT.mdoutlining project goals, validated requirements, context, constraints, and key decisions for open source onboarding and contribution..github/GOOD_FIRST_ISSUES.mdwith ready-to-use templates for onboarding new contributors via "good first issue" GitHub issues.GitHub Workflow & Templates
These changes collectively make it much easier for new contributors to get started, ensure consistent code quality, and clarify the project's roadmap and contribution process.