appkit

# AppKit

> A production-ready Reflex application and component workspace packaging Mantine UI wrappers, AI assistant tooling, enterprise authentication, and supporting infrastructure.

AppKit is a modular workspace-based project designed to accelerate development of robust web applications. The project emphasizes clean architecture, inheritance-based design patterns, and production-ready examples.

## Documentation

- [Project Overview](README.md): Primary project documentation, features, installation, and roadmap
- [Agent Guide](AGENTS.md): Comprehensive architecture snapshot, setup instructions, and development workflow for AI agents
- [Copilot Instructions](.github/copilot-instructions.md): Main instructions for Copilot, including golden rules and coding standards

## Components

- [Mantine UI](components/appkit-mantine/README.md): Core Mantine UI component wrappers for Reflex
- [Commons](components/appkit-commons/README.md): Shared configuration, logging, and database utilities
- [User Management](components/appkit-user/README.md): Authentication (OAuth), RBAC, and user administration
- [AI Assistant](components/appkit-assistant/README.md): LLM processor integration and MCP server management
- [Image Creator](components/appkit-imagecreator/README.md): Multi-provider image generation workflows
- [UI Shared](components/appkit-ui/README.md): Reusable layout components and UI patterns

## Developer Guidelines

- [Python Guidelines](.github/instructions/python.instructions.md): Python development standards and best practices
- [CI/CD Best Practices](.github/instructions/github-actions-ci-cd-best-practices.instructions.md): GitHub Actions workflow structure and security
- [Terraform Guidelines](.github/instructions/terraform.instructions.md): Terraform coding conventions
- [Azure Terraform](.github/instructions/terraform-azure.instructions.md): Specific guidelines for Azure resources via Terraform

## Configuration

- [Task Definitions](Taskfile.dist.yml): Definitive source of build, run, and utility commands (replaces Makefile)
- [Project Config](pyproject.toml): Workspace definition, dependencies, and tool settings (ruff, etc.)
- [Reflex Config](rxconfig.py): App structure, styling plugins, and service connectivity
- [Alembic Config](alembic.ini): Database migration settings
- [Environment Config](configuration/config.yaml): Base configuration structure

## Examples

- [App Entry](app/app.py): Main application entry point showing page registration
- [Assistant Page](app/pages/assistant/assistant.py): Implementation of the AI assistant interface
- [User Pages](app/pages/users.py): User management and profile implementation

- [Auto Scroll Examples](app/pages/examples/auto_scroll_examples.py): Automatic scrolling behavior patterns
- [Autocomplete Examples](app/pages/examples/autocomplete_examples.py): Auto-completing input with suggestions
- [Button Examples](app/pages/examples/button_examples.py): Button component usage with sizes, variants, loading states, and full-width demonstrations
- [Input Examples](app/pages/examples/input_examples.py): Text input patterns including basic, disabled, required, left/right sections
- [JSON Input Examples](app/pages/examples/json_input_examples.py): JSON editor with validation and formatting
- [Markdown Preview Examples](app/pages/examples/markdown_preview_examples.py): Usage of Markdown rendering component
- [Modal Examples](app/pages/examples/modal_examples.py): Dialog and modal window patterns
- [MultiSelect Examples](app/pages/examples/multi_select_examples.py): Multi-value selection with grouping and search
- [Nav Link Examples](app/pages/examples/nav_link_examples.py): Navigation link patterns
- [Navigation Progress Examples](app/pages/examples/nprogress_examples.py): Page loading progress bar with start/stop control
- [Number Formatter Examples](app/pages/examples/number_formatter_examples.py): Number formatting patterns
- [Number Input Examples](app/pages/examples/number_examples.py): Numeric input with min/max, decimal scaling, and formatting
- [Rich Select Examples](app/pages/examples/rich_select_examples.py): Advanced select component usage
- [Rich Text Editor Examples](app/pages/examples/tiptap_examples.py): Full-featured rich text editor with toolbars and formatting controls
- [Scroll Area Examples](app/pages/examples/scroll_area_examples.py): Custom scroll area implementation
- [Select Examples](app/pages/examples/select_examples.py): Dropdown selection with data binding and event handling
- [Table Examples](app/pages/examples/table_examples.py): Data table display and interactions
- [Tags Input Examples](app/pages/examples/tags_input_examples.py): Input for managing lists of tags
- [Textarea Examples](app/pages/examples/textarea_examples.py): Multi-line text input with resize, character count, and validation

## Testing & Quality Assurance

- [Test Configuration](pyproject.toml#tool.pytest.ini_options): Pytest settings, cache directory, test paths
- [Ruff Configuration](pyproject.toml#tool.ruff): Code linting and formatting with isort integration
- [MyPy Configuration](pyproject.toml#tool.mypy): Type checking configuration for Python 3.13
- [Coverage Configuration](pyproject.toml#tool.coverage.run): Test coverage settings with 80% minimum threshold

## GitHub Actions CI/CD

- [CI/CD Workflows](.github/workflows/): GitHub Actions for testing, linting, type checking, and deployment
- [Best Practices](.github/instructions/github-actions-ci-cd-best-practices.instructions.md): Comprehensive guide for robust and secure CI/CD pipelines

## Instructions & Guidelines

- [Python Instructions](.github/instructions/python.instructions.md): Python development guidelines and best practices for appkit
- [Terraform Instructions](.github/instructions/terraform.instructions.md): Terraform conventions and guidelines
- [Terraform Azure Instructions](.github/instructions/terraform-azure.instructions.md): Azure-specific Terraform best practices

## Project Structure

**Workspace Components:**
- `components/appkit-mantine/` - Mantine UI component wrappers with inheritance-based architecture
- `components/appkit-commons/` - Shared configuration, database, utilities, and registry
- `components/appkit-user/` - Authentication, user management, OAuth integration
- `components/appkit-assistant/` - AI assistant with LLM processors and MCP server support
- `components/appkit-imagecreator/` - Image generation with state management
- `components/appkit-ui/` - Reusable UI components and patterns

**Application:**
- `app/` - Demo application showcasing all components with example pages and state management
- `app/components/` - Application-level UI components (navbar, navigation)
- `app/pages/` - Example pages demonstrating each component type
- `app/pages/assitant/` - Assistant integration pages
- `app/pages/examples/` - Comprehensive examples for all input components

**Infrastructure:**
- `alembic/` - Database migrations and version control
- `configuration/` - Environment-specific configuration files (YAML-based)
- `assets/` - CSS, JavaScript, icons, and static files
- `.github/` - GitHub configuration, workflows, instructions, and prompts

## Optional

- [Architecture Deep Dive](components/appkit-mantine/README.md#project-architecture): Component architecture, integration patterns, event transformations
- [State Management Guide](app/pages/examples/tiptap_examples.py): Advanced state patterns with multiple editors and content management
- [Custom CSS Integration](components/appkit-mantine/README.md#critical-integration-patterns): Custom CSS and JavaScript injection patterns
- [Form Validation Patterns](components/appkit-user/src/appkit_user/user_management/pages.py): Password rules, validation helpers, async validation
- [MCP Server Integration](components/appkit-assistant/README.md): Model Context Protocol server management and integration
- [Alembic Migrations](alembic/versions/): Database schema evolution with multiple migration versions
- [Prompt Templates](.github/prompts/): Reusable prompt templates for common development tasks
- [Chat Modes Configuration](.github/chatmodes/): AI assistant chat mode configurations and integrations