Initial commit

Author: kmeng01

.cursor/rules/backend.mdc

@@ -0,0 +1,39 @@
+---
+description:
+globs: docent_core/_db_service/**/*.py,docent_core/services/**/*.py
+alwaysApply: false
+---
+# Sessions and services
+
+Application services should accept a DB session and required services. This way, transaction management is handled across services.
+
+```
+class Service:
+    def __init__(self, session: AsyncSession, ...services):
+        self.session = session
+        ...
+```
+
+In cases where services need to immediately commit results (e.g., computing searches), you can pass an additional writer_session_ctx factory:
+
+```
+class DiffService:
+    def __init__(
+        self,
+        session: AsyncSession,
+        writer_session_ctx: Callable[[], AsyncContextManager[AsyncSession]],
+        ...services,
+    ):
+        self.session = session
+        self.writer_session_ctx = writer_session_ctx
+        ...
+```
+
+Other notes:
+- Flushing and committing are the responsibility of the service *callers* (e.g., workers, HTTP handlers), not the service itself, except in rare cases.
+- Methods in services should accept SQLAlchemy model instances as input, *not* IDs. The caller is responsible for pulling the instance from the database and validating its existence. When used together with dependency injection, this also reduces calls to the database.
+- In services, make sure to distinguish variables pointing to SQLAlchemy model instances from Pydantic objects. Prefix variables pointing to SQLAlchemy model instances with `sq_`.
+
+# Polling vs pushing
+
+TODO(mengk)

.cursor/rules/frontend.mdc

@@ -0,0 +1,53 @@
+---
+description:
+globs: docent_core/_web/**/*.ts,docent_core/_web/**/*.tsx
+alwaysApply: false
+---
+# State management
+
+- Use Redux slices in `app/store` to store frontend state
+- Use RTK queries in `app/api` to access the backend through APIs.
+    - We're still migrating API calls from thunks to RTK queries. Do not change any existing thunks unless the user explicitly tells you to do a refactor. However, any new functionality should be implemented using the RTK pattern.
+
+# Styling
+
+## Padding, spacing, and height
+- For div containers, set padding and spacing to `3`, e.g., `p-3 space-y-3`
+
+## Color System
+
+**Base Layout Colors:**
+- `bg-background` - Main page/app background
+- `bg-secondary` - Secondary surfaces, sidebars, toolbars, panels
+- `border-border` - Standard borders and dividers
+
+**Text Colors:**
+- `text-primary` - Headings, emphasis, important text
+- `text-muted-foreground` - Subheadings, captions, softer text
+- Prefer `text-muted-foreground` against `bg-background`, `text-primary` against colored surfaces
+
+**Semantic Colors (use instead of generic destructive/success classes):**
+- **Blue**: `bg-blue-bg`, `border-blue-border`, `text-blue-text`, `bg-blue-muted` (hover states)
+- **Indigo**: `bg-indigo-bg`, `border-indigo-border`, `text-indigo-text`, `bg-indigo-muted` (search results, highlights)
+- **Green**: `bg-green-bg`, `border-green-border`, `text-green-text`, `bg-green-muted` (success, play buttons)
+- **Red**: `bg-red-bg`, `border-red-border`, `text-red-text`, `bg-red-muted` (errors, delete actions)
+- **Orange**: `bg-orange-bg`, `border-orange-border`, `text-orange-text` (warnings)
+- **Yellow**: `bg-yellow-bg`, `border-yellow-border`, `text-yellow-text`, `bg-yellow-muted`
+- **Purple**: `bg-purple-bg`, `border-purple-border`, `text-purple-text`
+
+**Border Usage:**
+- Default borders use `--border` variable automatically
+- For contrasting borders, use `border-primary/20` or semantic colors
+- Focus rings: rarely used, `ring-ring` available if needed
+
+**Hover States:**
+- Use `-muted` variants for subtle hover effects
+- For bright hover states, use low opacity `-text` variants (e.g., `hover:bg-red-text/10`)
+
+## Color System Rules
+
+1. **Never use arbitrary color values** - always use the defined color system
+2. **Use semantic colors over generic ones** - `text-red-text` not `text-destructive`
+3. **Maintain contrast** - `text-primary` on colored backgrounds, `text-muted-foreground` on neutral backgrounds
+4. **Follow the naming convention** - `bg-[color]-bg`, `border-[color]-border`, `text-[color]-text`
+5. **Check both light and dark modes** - all colors are defined for both themes in `globals.css`

.cursor/rules/local_setup.mdc

@@ -0,0 +1,5 @@
+---
+alwaysApply: false
+---
+
+See docs/self_hosting/self_host_docent.md for instructions on how to start the complete application. Use the **manual installation**, in which you can use Docker compose to start databases, but you must manually start each service. Use autoreload for the frontend. For the api server and worker, do **not** use autoreload; manually interrupt + restart the process after making a change.

.cursor/rules/schemas.mdc

@@ -0,0 +1,116 @@
+---
+description:
+globs: docent_core/_db_service/schemas/*.py,
+alwaysApply: false
+---
+
+# Misc rules
+
+- Always use `Mapped[T]` for type hints. This helps pyright understand the type of the column and raise type errors.
+
+# SQLA table specification
+
+## Foreign Keys and Relationships
+
+### Rule: Relationship Configuration
+Configure relationships with proper back-references and cascading:
+
+```python
+# Parent side
+instances: Mapped[list["SQLADiffInstance"]] = relationship(
+    "SQLADiffInstance",
+    back_populates="result",
+    cascade="all, delete-orphan",
+)
+
+# Child side
+result: Mapped["SQLADiffResult"] = relationship(
+    "SQLADiffResult",
+    back_populates="instances",
+)
+```
+
+**Key requirements**:
+- Use `Mapped[...]` type hints
+- Always specify `back_populates` for bidirectional relationships
+- Use `cascade="all, delete-orphan"` for parent-child relationships
+- Quote class names in relationships to handle forward references
+
+### Rule: Cascade Behavior
+Use `cascade="all, delete-orphan"` for parent-child relationships where:
+- Children should be deleted when parent is deleted
+- Children cannot exist without a parent
+
+**Example**: When a `DiffResult` is deleted, all its `DiffInstance` records should be deleted.
+
+## Column Specifications
+
+### Rule: Explicit Nullable Specification
+Always explicitly specify nullable behavior:
+
+```python
+summary = mapped_column(Text, nullable=False)
+focus = mapped_column(Text, nullable=True)
+```
+
+**Why**: Makes intent clear and prevents SQLAlchemy defaults from causing confusion.
+
+### Rule: Use Appropriate Column Types
+- `String(36)` for UUIDs
+- `Text` for long text content
+- `JSONB` for complex data structures
+- `Boolean` for true/false values
+
+### Rule: Index Foreign Keys
+Always add indexes to foreign key columns:
+
+```python
+collection_id = mapped_column(
+    String(36), ForeignKey(f"{TABLE_COLLECTION}.id"), nullable=False, index=True
+)
+```
+
+**Why**: Foreign keys are frequently used in JOINs and WHERE clauses.
+
+## Pydantic Integration
+
+### Rule: Implement Conversion Methods
+Every SQLAlchemy model must implement both conversion methods:
+
+```python
+@classmethod
+def from_pydantic(cls, model: PydanticModel, additional_params: str) -> "SQLAModel":
+    """Convert Pydantic model to SQLAlchemy model"""
+    return cls(
+        id=model.id,
+        # ... other fields
+    )
+
+def to_pydantic(self) -> PydanticModel:
+    """Convert SQLAlchemy model to Pydantic model"""
+    return PydanticModel(
+        id=self.id,
+        # ... other fields
+    )
+```
+
+### Rule: Handle Nested Relationships in Conversion
+When converting models with relationships, handle nested objects properly:
+
+```python
+@classmethod
+def from_pydantic(cls, diff_result: DiffResult, query_id: str) -> "SQLADiffResult":
+    sqla_instances = (
+        [
+            SQLADiffInstance.from_pydantic(instance, diff_result.id)
+            for instance in diff_result.instances
+        ]
+        if diff_result.instances is not None
+        else []
+    )
+    return cls(
+        id=diff_result.id,
+        instances=sqla_instances,
+        # ... other fields
+    )
+```