Python-ufa-lite

.gitignore

@@ -9,6 +9,7 @@ dist-ssr
 .env*
 .cache
 ./logs/
+venv/
 
 # Ignore scratch files - used for testing and development in Data Warehouse
 scratch*
@@ -32,4 +33,4 @@ nohup.out
 # Service-specific temp files
 services/*/temp_migration/
 services/*/dev-*.log
-services/*/.moose/
+services/*/.moose/

.vscode/settings.json

@@ -26,5 +26,20 @@
     ".*[Cc]lasses.*"
   ],
   "tailwindCSS.rootFontSize": 16,
-  "tailwindCSS.hooverPreview": true
+  "tailwindCSS.hooverPreview": true,
+  "sqltools.connections": [
+    {
+      "server": "http://localhost",
+      "port": 18123,
+      "database": "default",
+      "useJWT": false,
+      "requestTimeout": 30000,
+      "enableTls": false,
+      "previewLimit": 50,
+      "password": "pandapass",
+      "username": "panda",
+      "driver": "ClickHouse",
+      "name": "local"
+    }
+  ]
 }

CLAUDE.md

@@ -0,0 +1,224 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Area Code is a starter repository with multi-modal backend capabilities combining transactional (PostgreSQL), analytical (ClickHouse), and search (Elasticsearch) systems. Built with Turborepo, it includes two main applications: User Facing Analytics (UFA) and Operational Data Warehouse (ODW), plus a lightweight UFA-Lite variant.
+
+## Package Manager & Node Version
+
+- **Always use pnpm** (never npm)
+- **Required Node version: 20+** (required for Moose framework)
+- Package manager: `pnpm@10.14.0`
+
+## Development Commands
+
+### UFA (User Facing Analytics)
+```bash
+# Start all UFA services
+pnpm ufa:dev
+
+# Clean all UFA services and dependencies
+pnpm ufa:dev:clean
+
+# Seed databases with sample data (1M foo records, 100K bar records)
+pnpm ufa:dev:seed
+
+# Seed specific services
+pnpm ufa:dev:seed:transactional-supabase-foobar
+pnpm ufa:dev:seed:analytical-moose-foobar
+pnpm ufa:dev:seed:retrieval-elasticsearch-foobar
+```
+
+### UFA-Lite (without Elasticsearch)
+```bash
+# Start UFA-Lite services
+pnpm ufa-lite:dev
+
+# Clean UFA-Lite services
+pnpm ufa-lite:dev:clean
+
+# Seed UFA-Lite databases
+pnpm ufa-lite:dev:seed
+```
+
+### ODW (Operational Data Warehouse)
+```bash
+# Start ODW services
+pnpm odw:dev
+
+# Clean ODW services
+pnpm odw:dev:clean
+
+# Seed ODW databases
+pnpm odw:dev:seed
+```
+
+### Individual Service Development
+```bash
+# Frontend only
+pnpm --filter web-frontend-foobar dev
+
+# Transactional API only
+pnpm --filter transactional-supabase-foobar dev
+
+# Analytical API only
+pnpm --filter analytical-moose-foobar dev
+
+# Search API only (UFA only)
+pnpm --filter retrieval-elasticsearch-foobar dev
+```
+
+### Testing and Quality
+```bash
+# Build all packages
+turbo build
+
+# Lint all packages
+turbo lint
+
+# Type checking (service-specific)
+pnpm --filter <service-name> typecheck
+```
+
+## Project Structure
+
+This is a **Turborepo monorepo** with workspaces organized as:
+
+```
+area-code/
+├── ufa/                    # Full-featured UFA
+│   ├── apps/               # User-facing applications
+│   │   └── web-frontend-foobar/
+│   ├── services/           # Backend services
+│   │   ├── transactional-supabase-foobar/  # PostgreSQL + Fastify
+│   │   ├── analytical-moose-foobar/         # ClickHouse + Moose
+│   │   ├── retrieval-elasticsearch-foobar/ # Elasticsearch
+│   │   └── sync-supabase-moose-foobar/     # Data sync workflows
+│   └── packages/           # Shared packages
+│       ├── models/         # Data models
+│       ├── ui/             # UI components
+│       ├── eslint-config/  # ESLint config
+│       ├── typescript-config/
+│       └── tailwind-config/
+├── ufa-lite/              # Lightweight UFA (no Elasticsearch)
+│   ├── apps/
+│   └── services/
+└── odw/                   # Operational Data Warehouse
+    ├── apps/
+    ├── services/
+    └── packages/
+```
+
+## Architecture Components
+
+### UFA Stack
+- **Frontend**: Vite + React 19 + TypeScript + TanStack (Router, Query, Form, Table) + Tailwind CSS
+- **Transactional**: PostgreSQL + Fastify + Drizzle ORM + Supabase Realtime
+- **Analytical**: ClickHouse + Moose framework (API & Ingest)
+- **Search**: Elasticsearch (UFA only, not in UFA-Lite)
+- **Sync & Streaming**: Moose Workflows (Temporal) + Moose Stream (Redpanda)
+
+### Service Ports
+**UFA Ports:**
+- Frontend: http://localhost:5173
+- Transactional API: http://localhost:8080
+- Analytical Moose: http://localhost:4000 (proxy 4001, management 5001)
+- Retrieval API: http://localhost:8081
+- Sync Moose: http://localhost:4100 (management 5101)
+
+**UFA-Lite Ports:**
+- Transactional API: http://localhost:8082
+- Analytical Moose: http://localhost:4410 (proxy 4411, management 5411)
+- Sync Moose: http://localhost:4400 (management 5401)
+
+### Key Technologies
+- **Moose**: Framework for analytical APIs, streaming pipelines, and workflows
+- **Drizzle ORM**: TypeScript-first ORM for PostgreSQL
+- **Supabase**: PostgreSQL with realtime subscriptions
+- **ClickHouse**: Analytical database
+- **Elasticsearch**: Search engine (UFA only)
+- **Temporal**: Workflow orchestration
+- **Redpanda**: Event streaming
+
+## Development Workflow
+
+1. **Installation**: `pnpm install` (workspace root)
+2. **Start Services**: Use appropriate `pnpm <stack>:dev` command
+3. **Seed Data**: Use `pnpm <stack>:dev:seed` for sample data
+4. **Individual Development**: Use `--filter` for specific services
+
+### Moose Service Development
+- Moose services support **hot reload** - no manual restart needed
+- Test workflows: `moose workflow run <workflow-name>`
+- Moose CLI commands: `moose-cli dev`, `moose-cli build`, `moose-cli clean`
+
+### Package Naming Convention
+- Prefix shared packages with `@workspace/`
+- Examples: `@workspace/models`, `@workspace/ui`, `@repo/eslint-config`
+
+## Environment Setup
+
+### Required for AI Chat Feature (Optional)
+Create `.env.local` in `services/transactional-supabase-foobar/`:
+```bash
+ANTHROPIC_API_KEY=your-api-key-here
+```
+
+### UFA-Lite Frontend Environment
+Create `.env.development.local` in `ufa-lite/apps/web-frontend-foobar/`:
+```bash
+VITE_ENABLE_SEARCH=false
+VITE_TRANSACTIONAL_API_BASE=http://localhost:8082
+VITE_ANALYTICAL_CONSUMPTION_API_BASE=http://localhost:4410
+VITE_SUPABASE_URL=http://localhost:54321
+VITE_SUPABASE_ANON_KEY=dev-anon-key
+```
+
+## Database Management
+
+### Transactional Services (PostgreSQL/Supabase)
+```bash
+# Start database
+pnpm --filter transactional-supabase-foobar db:start
+
+# Stop database
+pnpm --filter transactional-supabase-foobar db:stop
+
+# Run migrations
+pnpm --filter transactional-supabase-foobar db:migrate
+
+# Generate migrations
+pnpm --filter transactional-supabase-foobar db:generate
+```
+
+## Troubleshooting
+
+### Memory Requirements
+- Elasticsearch requires 4GB+ RAM
+- Tested on Mac M3/M4 Pro with 18GB+ RAM
+
+### Reset Environment
+```bash
+# Clean all services and dependencies
+pnpm <stack>:dev:clean
+
+# Restart development
+pnpm <stack>:dev
+```
+
+### Common Issues
+1. **Node Version**: Ensure Node 20+ for Moose compatibility
+2. **Memory**: Insufficient RAM for Elasticsearch
+3. **Port Conflicts**: Check that required ports are available
+4. **Service Dependencies**: Ensure all services start in correct order
+
+## Important Notes
+
+- **Never use npm** - always use pnpm
+- **Don't override .env files** - use .env.local for local overrides
+- Moose services require Node 20+
+- UFA-Lite omits Elasticsearch for lighter resource usage
+- All stacks share containers (Postgres, ClickHouse, Redpanda, Temporal)
+- Use `tmux-agent-cmd.sh` wrapper for command execution if available

ufa-lite/services/analytical-moose-foobar-py/.gitignore

@@ -0,0 +1,57 @@
+# Moose specific
+.moose
+.sloan
+
+# Python bytecode and cache
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache
+.mypy_cache
+.hypothesis
+.coverage
+
+# Python virtual environments
+.Python
+env
+.venv
+venv
+ENV
+env.bak
+
+# IDE and editor files
+.spyderproject
+.ropeproject
+.idea
+*.ipynb_checkpoints
+.cache
+.cursor
+
+# Build and distribution
+*.so
+*.egg
+*.egg-info
+dist
+build
+develop-eggs
+downloads
+eggs
+lib
+lib64
+parts
+sdist
+var
+wheels
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Coverage reports
+cover
+*.cover
+
+# OS specific
+.DS_Store
+

ufa-lite/services/analytical-moose-foobar-py/.vscode/extensions.json

@@ -0,0 +1,9 @@
+{
+  "recommendations": [
+    "frigus02.vscode-sql-tagged-template-literals-syntax-only",
+    "mtxr.sqltools",
+    "ultram4rine.sqltools-clickhouse-driver",
+    "jeppeandersen.vscode-kafka",
+    "rangav.vscode-thunder-client"
+  ]
+}

ufa-lite/services/analytical-moose-foobar-py/.vscode/settings.json

@@ -0,0 +1,17 @@
+{
+  "sqltools.connections": [
+    {
+      "server": "localhost",
+      "port": 18123,
+      "useHTTPS": false,
+      "database": "local",
+      "username": "panda",
+      "enableTls": false,
+      "password": "pandapass",
+      "driver": "ClickHouse",
+      "name": "moose clickhouse"
+    }
+  ],
+  "python.analysis.extraPaths": [".moose/versions"],
+  "python.analysis.typeCheckingMode": "basic"
+}

ufa-lite/services/analytical-moose-foobar-py/README.md

@@ -0,0 +1,48 @@
+# Template: Python (Empty)
+
+This is an empty Python-based Moose template that provides a minimal foundation for building data-intensive applications using Python.
+
+[![PyPI Version](https://img.shields.io/pypi/v/moose-cli?logo=python)](https://pypi.org/project/moose-cli/)
+[![Moose Community](https://img.shields.io/badge/slack-moose_community-purple.svg?logo=slack)](https://join.slack.com/t/moose-community/shared_invite/zt-2fjh5n3wz-cnOmM9Xe9DYAgQrNu8xKxg)
+[![Docs](https://img.shields.io/badge/quick_start-docs-blue.svg)](https://docs.fiveonefour.com/moose/getting-started/quickstart)
+[![MIT license](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
+
+## Getting Started
+
+### Prerequisites
+
+* [Docker Desktop](https://www.docker.com/products/docker-desktop/)
+* [Python](https://www.python.org/downloads/) (version 3.8+)
+* [An Anthropic API Key](https://docs.anthropic.com/en/api/getting-started)
+* [Cursor](https://www.cursor.com/) or [Claude Desktop](https://claude.ai/download)
+
+### Installation
+
+1. Install Moose CLI: `pip install moose-cli`
+2. Create project: `moose init <project-name> python-empty`
+3. Install dependencies: `cd <project-name> && pip install -r requirements.txt`
+4. Run Moose: `moose dev`
+
+You are ready to go! You can start editing the app by modifying primitives in the `app` subdirectory.
+
+## Learn More
+
+To learn more about Moose, take a look at the following resources:
+
+- [Moose Documentation](https://docs.fiveonefour.com/moose) - learn about Moose.
+- [Sloan Documentation](https://docs.fiveonefour.com/sloan) - learn about Sloan, the MCP interface for data engineering.
+
+## Community
+
+You can join the Moose community [on Slack](https://join.slack.com/t/moose-community/shared_invite/zt-2fjh5n3wz-cnOmM9Xe9DYAgQrNu8xKxg). Check out the [MooseStack repo on GitHub](https://github.com/514-labs/moosestack).
+
+## Deploy on Boreal
+
+The easiest way to deploy your MooseStack Applications is to use [Boreal](https://www.fiveonefour.com/boreal) from 514 Labs, the creators of Moose.
+
+[Sign up](https://www.boreal.cloud/sign-up).
+
+## License
+
+This template is MIT licensed.
+