Rivertalk/river_connect/.agent/rules/tech-stack-structure.md

trigger

trigger
always_on

Elixir & Solid.js Bridge Architecture

This project uses a hybrid architecture where Phoenix LiveView manages the server-side state and Solid.js handles the reactive client-side UI via a "Bridge Hook".

1. Core Architecture

• State Source of Truth: socket.assigns in Elixir LiveViews.
• Transport: JSON payloads via push_event/3 (Server -> Client) and pushEvent (Client -> Server).
• Client Container: A div with phx-update="ignore", a unique id, and phx-hook="SolidBridge".
• Reactivity: A Phoenix Hook initializes a Solid.js Store. Server events trigger setState on the store, which drives Solid's fine-grained reactivity.

2. Frontend Build Pipeline

• Bundler: Custom esbuild script (build.js).
• Runtime: bun is used for dependency management and running the build script.
• JSX Support: Solid.js JSX is compiled via esbuild-plugin-solid.
• Dependency Paths:
  • Phoenix dependencies (js) are loaded from package.json (npm versions).
  • Aliases: phoenix-colocated is shimmed to js/phoenix-colocated-shim.js to prevent dynamic require errors.

3. Directory Structure & Key Files

• lib/river_connect_web/live/: Elixir LiveView components.
• assets/js/hooks/SolidBridge.jsx: The Phoenix Hook that spawns Solid.
• assets/js/components/: Solid.js reactive components (.jsx).
• priv/static/assets/js/app.js: Generated bundle (Target for esbuild).

4. State Syncing Patterns

Server to Client (Push)

# lib/app_live.ex
def handle_event("update", _params, socket) do
  new_state = %{count: 1}
  {:noreply, push_event(socket, "sync_state", new_state)}
end

Client to Server (Push)

// assets/js/components/MyComponent.jsx
const update = () => props.push("client_event", { data: "payload" });

5. UI Components & Styling

• Styling: Tailwind CSS + DaisyUI.
• Headless UI: Kobalte is used for complex UI logic (Popovers, Tooltips, Tabs) while maintaining total style control.
• Glassmorphism: Use .glass helper in CSS for translucent, blurred backgrounds.

6. Development Workflow

• Watchers: Run automatically via mix phx.server (Configured in config/dev.exs using bun).
• Manual Build: bun run --prefix assets build.
• Adding Dependencies: Use bun add in the assets/ directory.

7. Important Constraints

• NEVER use phx-update="replace" on Solid.js root containers; it will destroy the Solid DOM tree.
• ALWAYS use phx-update="ignore" for Solid mounts.
• JSX in JS: The build script is configured to treat .js files as JSX, but preferred extension for Solid components is .jsx.