Lists Sharing App Context

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.

What This Skill Does

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.

Instructions for AI Agents

1. Understand the Architecture First

Before making any changes, familiarize yourself with:

2. Critical Permission System Rules

**List Permissions:**

**Entry Permissions:**

**Key Principle**: List collaborators manage list membership. Entry permissions control content modification. These are completely separate concerns.

3. Code Organization Standards

**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

```

4. When Making Changes

**Always:**

**Never:**

5. Common Tasks

**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`

6. API Endpoint Reference

**Entries** (`/api/entries`):

**Lists** (`/api/lists`):

**Groups** (`/api/groups`):

**Auth** (`/api/auth`):

7. Testing Strategy

When adding features:

8. Security Guidelines

9. Documentation Maintenance

**CRITICAL**: After making any changes, update the CLAUDE.md file in the repository to reflect:

This ensures future agents have accurate context.

Key Files to Reference

Running the Application

```bash

Install dependencies

uv sync --all-extras

Apply database migrations

uv run alembic upgrade head

Start development server

uv run flask --app app.main:create_app run --debug

```

Common Pitfalls to Avoid

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

When You Need Help

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.