Complete implementation context for a Flask-based lists sharing application with OAuth, permissions, and multi-list entry management
A comprehensive context file for working with a Flask-based lists sharing application that supports OAuth authentication, granular permissions, and flexible entry management across multiple lists.
This skill provides complete architectural context and implementation guidelines for a lists sharing application. It helps AI agents understand the codebase structure, design decisions, permission model, and coding standards to make consistent, well-informed modifications.
Before making any changes, familiarize yourself with:
**List Permissions:**
**Entry Permissions:**
**Key Principle**: List collaborators manage list membership. Entry permissions control content modification. These are completely separate concerns.
**CRITICAL IMPORT RULE**: ALL imports MUST be at the top level of Python files. Never place imports inside functions, methods, or conditional blocks (except TYPE_CHECKING blocks for type hints).
**Directory Structure:**
```
app/
├── models/ # SQLAlchemy models (base, user, group, list, entry)
├── schemas/ # Pydantic validation schemas
├── services/ # Business logic (auth, permissions, security)
├── api/ # API endpoint blueprints
└── main.py # Application factory
```
**Always:**
**Never:**
**Adding a new API endpoint:**
1. Create Pydantic schemas in `app/schemas/`
2. Add business logic to appropriate service in `app/services/`
3. Create endpoint in `app/api/` with authentication/permission decorators
4. Update this documentation with the new endpoint
**Modifying permissions:**
1. Review the separate list/entry permission models
2. Update `app/services/permissions.py` if needed
3. Apply appropriate decorators to affected endpoints
4. Write tests for permission scenarios
**Database schema changes:**
1. Update SQLAlchemy models in `app/models/`
2. Generate migration: `uv run alembic revision --autogenerate -m "description"`
3. Review generated migration file
4. Apply: `uv run alembic upgrade head`
**Entries** (`/api/entries`):
**Lists** (`/api/lists`):
**Groups** (`/api/groups`):
**Auth** (`/api/auth`):
When adding features:
**CRITICAL**: After making any changes, update the CLAUDE.md file in the repository to reflect:
This ensures future agents have accurate context.
```bash
uv sync --all-extras
uv run alembic upgrade head
uv run flask --app app.main:create_app run --debug
```
1. **Confusing list permissions with entry permissions** - They are separate systems
2. **Hard deleting records** - Always use soft deletes (`deleted_at`)
3. **Putting imports in functions** - All imports at top level
4. **Skipping input validation** - Always use Pydantic schemas
5. **Forgetting to update documentation** - Keep CLAUDE.md current
This skill provides context for understanding the codebase structure and conventions. For specific implementation tasks:
Always maintain consistency with the established patterns and update documentation as you work.
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/lists-sharing-app-context/raw