Set up Python monorepo structure with three packages

.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      matrix:
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e packages/core[dev]
+        pip install -e packages/utils[dev]
+        pip install -e packages/api[dev]
+
+    - name: Lint with ruff
+      run: make lint
+
+    - name: Test with pytest
+      run: make test
+
+  format-check:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Check formatting with ruff
+      run: |
+        pip install ruff
+        ruff format --check packages/

CONTRIBUTING.md

@@ -0,0 +1,115 @@
+# Contributing to ModPocket
+
+Thank you for your interest in contributing to ModPocket! This document provides guidelines for contributing to this monorepo project.
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/ModPocket.git
+   cd ModPocket
+   ```
+3. Install all packages in development mode:
+   ```bash
+   make install-dev
+   ```
+
+## Development Workflow
+
+### Making Changes
+
+1. Create a new branch:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. Make your changes in the appropriate package(s)
+
+3. Test your changes:
+   ```bash
+   make test
+   ```
+
+4. Lint and format your code:
+   ```bash
+   make format
+   make lint
+   ```
+
+5. Commit your changes:
+   ```bash
+   git add .
+   git commit -m "Description of your changes"
+   ```
+
+6. Push to your fork:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+7. Open a Pull Request
+
+### Code Style
+
+- Follow PEP 8 guidelines
+- Use ruff for linting and formatting
+- Add docstrings to all public functions and classes
+- Keep functions focused and small
+
+### Testing
+
+- Write tests for all new features
+- Ensure all tests pass before submitting a PR
+- Aim for high test coverage
+
+### Commit Messages
+
+- Use clear, descriptive commit messages
+- Start with a verb in present tense (Add, Fix, Update, etc.)
+- Reference issue numbers when applicable
+
+Example:
+```
+Add user authentication feature to API package
+
+- Implement JWT token generation
+- Add login and logout endpoints
+- Update tests
+
+Fixes #123
+```
+
+## Package-Specific Guidelines
+
+### Core Package
+- Contains fundamental functionality used by other packages
+- Should have minimal external dependencies
+- Changes here may affect all other packages
+
+### Utils Package
+- Utility functions and helpers
+- Should be stateless and pure when possible
+- Well-documented with usage examples
+
+### API Package
+- API interfaces and endpoints
+- Should follow RESTful conventions
+- Include comprehensive API documentation
+
+## Pull Request Process
+
+1. Update documentation to reflect changes
+2. Add tests for new functionality
+3. Ensure all tests pass
+4. Update the package version if applicable
+5. Request review from maintainers
+
+## Questions or Issues?
+
+- Open an issue for bugs or feature requests
+- Use discussions for questions and general conversation
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the same license as the project.

MONOREPO.md

@@ -0,0 +1,177 @@
+# ModPocket Monorepo Structure
+
+This document explains the monorepo structure and how to work with it.
+
+## What is a Monorepo?
+
+A monorepo (monolithic repository) is a software development strategy where code for many projects is stored in the same repository. This approach offers several benefits:
+
+- **Code Sharing**: Easy to share code between packages
+- **Atomic Changes**: Make changes across multiple packages in a single commit
+- **Unified Versioning**: Manage versions consistently across packages
+- **Simplified Dependency Management**: All packages use the same dependency versions
+
+## Repository Structure
+
+```
+ModPocket/
+├── packages/               # All packages live here
+│   ├── core/              # Core functionality
+│   │   ├── modpocket_core/    # Python package
+│   │   ├── pyproject.toml     # Package config
+│   │   └── README.md          # Package docs
+│   ├── utils/             # Utility functions
+│   │   ├── modpocket_utils/
+│   │   ├── pyproject.toml
+│   │   └── README.md
+│   └── api/               # API interfaces
+│       ├── modpocket_api/
+│       ├── pyproject.toml
+│       └── README.md
+├── scripts/               # Helper scripts
+│   └── install-all.sh     # Install all packages
+├── pyproject.toml         # Root configuration
+├── Makefile              # Common tasks
+└── README.md             # Main documentation
+```
+
+## Working with the Monorepo
+
+### Installing Packages
+
+**Install all packages in development mode:**
+```bash
+make install-dev
+```
+
+Or use the installation script:
+```bash
+./scripts/install-all.sh
+```
+
+**Install individual packages:**
+```bash
+pip install -e packages/core[dev]
+pip install -e packages/utils[dev]
+pip install -e packages/api[dev]
+```
+
+### Available Make Commands
+
+- `make help` - Show available commands
+- `make install` - Install all packages
+- `make install-dev` - Install all packages with dev dependencies
+- `make clean` - Remove build artifacts
+- `make test` - Run tests for all packages
+- `make lint` - Lint all packages with ruff
+- `make format` - Format all packages with ruff
+
+### Adding a New Package
+
+1. Create a new directory under `packages/`:
+```bash
+mkdir -p packages/newpackage/modpocket_newpackage
+```
+
+2. Create the package's `__init__.py`:
+```python
+"""ModPocket New Package."""
+
+__version__ = "0.1.0"
+```
+
+3. Create `pyproject.toml`:
+```toml
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "modpocket-newpackage"
+version = "0.1.0"
+description = "Description of the new package"
+readme = "README.md"
+requires-python = ">=3.8"
+authors = [
+    {name = "ModPocket Team"}
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "ruff>=0.1.0",
+]
+```
+
+4. Create a `README.md` for the package
+
+5. Update the root `Makefile` to include the new package
+
+6. Install the package:
+```bash
+pip install -e packages/newpackage[dev]
+```
+
+### Cross-Package Dependencies
+
+To use one package in another, add it as a dependency in the `pyproject.toml`:
+
+```toml
+[project]
+dependencies = [
+    "modpocket-core>=0.1.0",
+]
+```
+
+Then install both packages in development mode:
+```bash
+pip install -e packages/core
+pip install -e packages/dependent-package
+```
+
+### Testing
+
+Run tests for all packages:
+```bash
+make test
+```
+
+Or run tests for a specific package:
+```bash
+pytest packages/core/
+```
+
+### Code Quality
+
+**Linting:**
+```bash
+make lint
+```
+
+**Formatting:**
+```bash
+make format
+```
+
+## Best Practices
+
+1. **Keep packages focused**: Each package should have a single, well-defined purpose
+2. **Minimize cross-package dependencies**: Reduces coupling and makes packages more reusable
+3. **Use consistent naming**: Follow the `modpocket_*` naming convention
+4. **Document changes**: Update package READMEs when adding new features
+5. **Test thoroughly**: Ensure changes don't break other packages
+6. **Version together**: Consider versioning all packages together for simplicity
+
+## Troubleshooting
+
+**Import errors after installation:**
+- Ensure you're in the correct virtual environment
+- Try reinstalling the package: `pip install -e packages/packagename --force-reinstall`
+
+**Make commands fail:**
+- Ensure you have all required dependencies installed
+- Check that you're in the repository root directory
+
+**Package not found:**
+- Verify the package structure matches the expected format
+- Check that the package name in `pyproject.toml` matches the directory name

Makefile

@@ -0,0 +1,38 @@
+.PHONY: help install install-dev clean test lint format
+
+help:
+	@echo "ModPocket Monorepo Commands:"
+	@echo "  make install        - Install all packages"
+	@echo "  make install-dev    - Install all packages in development mode with dev dependencies"
+	@echo "  make clean          - Clean build artifacts"
+	@echo "  make test           - Run tests for all packages"
+	@echo "  make lint           - Lint all packages"
+	@echo "  make format         - Format all packages"
+
+install:
+	pip install -e packages/core
+	pip install -e packages/utils
+	pip install -e packages/api
+
+install-dev:
+	pip install -e packages/core[dev]
+	pip install -e packages/utils[dev]
+	pip install -e packages/api[dev]
+
+clean:
+	find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name ".pytest_cache" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name ".ruff_cache" -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete
+
+test:
+	pytest packages/core/tests -v
+	pytest packages/utils/tests -v
+	pytest packages/api/tests -v
+
+lint:
+	ruff check packages/
+
+format:
+	ruff format packages/