Skip to content

Instantly share code, notes, and snippets.

@wiiiimm

wiiiimm/Cursor-CLAUDE-4-README-OUTPUT.md

Last active August 29, 2025 08:17
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save wiiiimm/2c6c00e208f77b577b99392f9256f523 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save wiiiimm/2c6c00e208f77b577b99392f9256f523 to your computer and use it in GitHub Desktop.
Download ZIP
AI Code Analysis with Different Models
Raw
Cursor-CLAUDE-4-README-OUTPUT.md

Echo Roaster eNurse CMS

A comprehensive healthcare communication management system built with Next.js and Supabase for managing patient communications, scheduling, and templates.

🏥 Overview

Echo Roaster eNurse CMS is a full-stack healthcare communication platform designed for medical institutions to manage patient contact databases, create communication templates, schedule automated messages, and track conversation threads. The system enables healthcare professionals to maintain organized patient communications while ensuring compliance and efficiency.

🏗️ Architecture

Monorepo Structure

echoroaster-enurse-cms/
├── nextjs/                    # Main Next.js application
│   ├── pages/                # Application pages and API routes
│   ├── components/           # Reusable UI components
│   ├── styles/              # Global styles and Tailwind config
│   └── public/              # Static assets
├── packages/
│   └── lib/                 # Shared business logic library
│       └── src/             # Helper modules and utilities
└── scripts/                 # Deployment and utility scripts

Technology Stack

Frontend:

  • Next.js 13+ - React framework with SSR/SSG capabilities
  • React 18 - UI library with modern hooks
  • Tailwind CSS - Utility-first CSS framework with custom design system
  • React Hot Toast - Notification system
  • Headless UI - Accessible UI components

Backend & Database:

  • Supabase - PostgreSQL database with real-time subscriptions
  • Next.js API Routes - RESTful API endpoints
  • Row Level Security (RLS) - Database-level authorization

Communication & Media:

  • React Player - Video/audio playback
  • React Audio Player - Audio message handling
  • File Upload System - Support for attachments and media

Development & Deployment:

  • Docker - Containerized deployment
  • ESLint - Code linting and formatting
  • SWC - Fast JavaScript/TypeScript compiler
  • GitLab CI/CD - Automated deployment pipeline

🚀 Quick Start

Prerequisites

  • Docker and Docker Compose
  • Node.js 16+ (for local development)
  • Access to Supabase instance

Docker Deployment (Recommended)

  1. Build the container:

    npm run docker-build

  2. Start the application:

    npm run docker-start

  3. Access the application:

Local Development

  1. Install dependencies:

    cd nextjs && npm install
cd ../packages/lib && npm install

  2. Configure environment:

    # Create nextjs/.env with required variables
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
SERVICE_KEY=your_service_key

  3. Start development server:

    cd nextjs && npm run dev

🎯 Core Features

📊 Dashboard & Analytics

  • Real-time metrics - Message delivery statistics and recipient reach
  • Chart visualizations - Time-series data with Chart.js integration
  • Schedule overview - Active and pending communication schedules
  • Quick actions - Template creation and contact management shortcuts

👥 Contact Management

  • Contact database - Comprehensive patient/client information storage
  • Contact groups - Organize contacts into categories (departments, specialties, etc.)
  • Bulk operations - Import/export via CSV, batch group assignments
  • Search & filtering - Fuzzy search with Fuse.js, advanced filtering options
  • Phone validation - International phone number formatting and validation

📝 Template System

  • Rich text templates - HTML-supported message templates with variable substitution
  • Media attachments - Support for images, audio, video, and documents
  • Template groups - Organized template categories
  • Metadata integration - Dynamic content insertion with custom meta fields
  • Preview system - Real-time template preview with variable resolution

⏰ Scheduling Engine

  • Flexible scheduling - One-time and recurring message schedules
  • Recipient targeting - Contact groups and individual contact selection
  • Job queue management - Background job processing with status tracking
  • Retry mechanisms - Automatic retry for failed deliveries
  • Cancellation support - Cancel pending schedules and jobs

💬 Chat Management

  • Conversation threads - Organized message history per contact
  • Real-time messaging - Live chat interface with instant updates
  • Message status tracking - Delivery, read receipts, and error handling
  • Media sharing - Image, audio, video, and file attachments
  • Emoji support - Rich emoji picker integration
  • Message search - Full-text search across conversation history

🔐 Authentication & Authorization

  • Supabase Auth - Secure authentication with magic links
  • Role-based access control - Granular permissions for different user types
  • Profile management - User profile and preference management
  • Session management - Secure token handling and session persistence

🛠️ API Architecture

RESTful Endpoints

All API routes follow the pattern /api/{resource}/[[...id]].js supporting:

  • GET /api/{resource} - List resources with pagination
  • GET /api/{resource}/{id} - Get specific resource
  • POST /api/{resource} - Create new resource
  • PUT /api/{resource}/{id} - Update existing resource
  • DELETE /api/{resource}/{id} - Delete resource

Key API Resources

  • /api/contacts - Contact management
  • /api/templates - Template CRUD operations
  • /api/schedules - Schedule management
  • /api/chats - Message and conversation handling
  • /api/users - User and profile management
  • /api/roles - Role and permission management
  • /api/charts - Analytics data endpoints

Database Schema Overview

Core Entities:

  • contacts - Patient/client information
  • contact_groups - Contact categorization
  • contacts_in_groups - Many-to-many contact-group relationships
  • templates - Message templates
  • template_groups - Template categorization
  • schedules - Scheduled communications
  • jobs - Background job queue
  • chats - Message threads and conversations
  • profiles - User profiles and settings
  • roles - User roles and permissions
  • metas - Custom metadata fields

🎨 UI/UX Design System

Color Palette

  • Teal (#81D8D0) - Primary healthcare brand color
  • Blue (#648DE5) - Secondary actions and links
  • Green (#07C180) - Success states and confirmations
  • Red (#DB5375) - Errors and warnings
  • Orange (#FF9931) - Attention and highlights
  • Grey Scale - Neutral colors for text and backgrounds

Component Library

  • Modular components - Reusable UI elements in /components
  • Consistent styling - Tailwind CSS utility classes
  • Accessibility - ARIA-compliant components with keyboard navigation
  • Responsive design - Mobile-first approach with breakpoint system

🔄 Development Workflow

Shared Library (packages/lib)

The shared library provides business logic and utilities:

  • Helper modules - ContactHelpers, MessageHelpers, ScheduleHelpers, TemplateHelpers
  • API utilities - Authentication, error handling, and common operations
  • Supabase client - Centralized database connection management
  • Type definitions - Shared TypeScript interfaces (when applicable)

Real-time Features

  • Supabase subscriptions - Live updates for templates, schedules, and messages
  • React state management - Efficient state updates with real-time data
  • WebSocket connections - Persistent connections for chat functionality

🚀 Deployment

Production Environment

The application uses multi-stage Docker builds optimized for production:

  1. Dependencies stage - Install and cache dependencies
  2. Build stage - Compile Next.js application
  3. Runtime stage - Minimal production image with security hardening

Environment Configuration

Required environment variables:

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
SERVICE_KEY=your_service_role_key

# Application Configuration
NODE_ENV=production
PORT=3000

Database Migration Scripts

Database synchronization utilities for different environments:

  • dbDev2UAT - Development to UAT migration
  • dbDev2Prod - Development to Production migration
  • dbUAT2Prod - UAT to Production migration
  • dbProd2UAT - Production to UAT rollback

📊 Monitoring & Analytics

Built-in Analytics

  • Message delivery rates - Track successful vs failed message deliveries
  • Recipient engagement - Monitor read receipts and response rates
  • System performance - API response times and error rates
  • User activity - Login patterns and feature usage

Health Checks

  • /api/status - System health and version information
  • Real-time connection status monitoring
  • Database connectivity verification

🤝 Contributing

Development Setup

  1. Fork and clone the repository
  2. Install dependencies: npm install in both nextjs/ and packages/lib/
  3. Set up environment variables
  4. Run development server: npm run dev

Code Style

  • ESLint configuration for consistent code formatting
  • Prettier integration for automatic code formatting
  • Tailwind CSS for styling consistency

Testing

  • Component testing with React Testing Library
  • API testing with Jest
  • E2E testing setup ready for Cypress/Playwright

📚 Additional Resources

Documentation

Support

  • Check the Wiki for detailed technical documentation
  • Review system architecture diagrams for component relationships
  • Consult API documentation for integration guidelines

Version: 1.0.0 (NextJS) | 1.0.17 (Library)
License: Private - All rights reserved
Maintainer: BBI HQ Team

Raw
Cursor-GTP-5-DETAILED-PROMPT-README-OUTPUT.md

eNurse CMS

A Next.js-based CMS for messaging workflows integrated with Supabase (Postgres + Storage) and an external messaging service (ER). The app provides role-based access, contact and template management, scheduling, and audit of chat message delivery.

Links to in-repo docs:

  • Architecture overview: docs/architecture/overview.md
  • Modules: docs/architecture/modules.md
  • Sequences: docs/architecture/sequences.md
  • Data models (ERD): docs/data/models.md
  • Environments & ops: docs/ops/environments.md
  • Observability: docs/ops/observability.md
  • Security & threat model: docs/security/threat-model.md
  • Decisions (ADRs): docs/decisions/adrs.md
  • Contributing: docs/contributing.md
  • Roadmap & gaps: docs/roadmap.md

Quick start

Prerequisites:

  • Node.js v16.14.2 (see .nvmrc)
  • npm 8+ (or yarn if you prefer, but npm commands are shown)
  • Supabase project (URL, anon key, and service key)

Local development (without private registry access):

  1. Install the shared library locally and build it:
cd packages/lib
npm i
npm run build
  1. Install the Next.js app and link the local library:
cd ../../nextjs
npm i ../packages/lib
npm i
  1. Create nextjs/.env with required variables (see env matrix below or docs/ops/environments.md):
NEXT_PUBLIC_SUPABASE_URL=...
NEXT_PUBLIC_SUPABASE_ANON_KEY=...
SERVICE_KEY=...
APP_SECRET=...
APP_API_ENDPOINT=http://localhost:3000/api
ER_ENDPOINT=https://<er-host>
NEXT_PUBLIC_VERCEL_ENV=development
  1. Run the app:
npm run dev

Container (Docker):

cd nextjs
npm run docker-build
npm run docker-start
# background: npm run docker-start-bg
# stop:       npm run docker-stop
# cleanup:    npm run docker-cleanup

Note: The Dockerfile builds with Node 16 and expects dependencies to be installable from the registry. If @bbihq/echoroaster-enurse-cms-lib is private, configure an auth token for the registry or prebuild + vendor the package as documented in docs/ops/environments.md.

Tech stack & versions

  • Next.js ^13 (pages router)
  • React 18
  • Tailwind CSS 3 (JIT)
  • Supabase JS ^1.35 (auth, Postgres, storage)
  • Node 16.14.2 for runtime (see .nvmrc and nextjs/Dockerfile)

Architecture (preview)

See docs/architecture/overview.md for full diagrams and details.

User → Next.js (UI + API routes) → Supabase (Auth, Postgres, Storage)
                             ↘  ER (external messaging service)

Configuration & environment variables (matrix)

For details and defaults, see docs/ops/environments.md.

  • NEXT_PUBLIC_SUPABASE_URL: Supabase project URL (public)
  • NEXT_PUBLIC_SUPABASE_ANON_KEY: Supabase anon key (public)
  • SERVICE_KEY: Supabase service role key (server-side only)
  • APP_SECRET: Shared secret to authorise ER calls and service-mode requests
  • APP_API_ENDPOINT: Base URL for this app’s API (used in callbacks)
  • ER_ENDPOINT: Base URL of the ER service
  • NEXT_PUBLIC_VERCEL_ENV: Environment label used for storage paths (e.g., development/preview/production)
  • PORT: Server port when running the Docker container (default 3000)

Common workflows

  • Lint: cd nextjs && npm run lint
  • Build: cd nextjs && npm run build
  • Start (prod): cd nextjs && npm run start
  • Release shared lib: cd packages/lib && npm run build-publish-patch (requires registry access)

Troubleshooting

  • Private dependency not found: Ensure registry auth for @bbihq/* or install the local packages/lib before installing the app. See steps above.
  • Supabase auth failures: Verify NEXT_PUBLIC_SUPABASE_URL, keys, and that your user has expected roles in profiles/user_roles.
  • Attachments return 404: Ensure the attachments bucket exists and objects are written under /${NEXT_PUBLIC_VERCEL_ENV}/... paths.

Repository layout

  • nextjs/: Next.js app (UI, API routes, Dockerfile, Tailwind, ESLint)
  • packages/lib/: Shared library consumed by the app (helpers, Supabase client)
  • scripts/: Operational scripts (e.g., GitLab migration/push)
  • docs/: Architecture, ops, and security documentation with Mermaid diagrams

For deeper detail, open the docs in the docs/ folder.

Raw
Cursor-GTP-5-README-OUTPUT.md

eNurse CMS (Echoroaster)

A monorepo for the eNurse CMS web application and shared library.

  • App: nextjs/ — Next.js 13 app (React 18), TailwindCSS, API routes
  • Shared library: packages/lib/ — Supabase client and business logic (contacts, templates, schedules, messages)
  • Data layer: Supabase (Postgres, Auth, Storage)

Tech stack

  • Next.js 13 (React 18), TailwindCSS
  • Supabase: @supabase/supabase-js v1.x
  • Node.js v16.14.2 (.nvmrc)
  • Docker (production build via multi-stage Dockerfile)

Prerequisites

  • Node.js v16.14.2 (use nvm use)
  • Supabase project with the following:
    • Postgres schema matching tables used by the app: contacts, contact_groups, contacts_in_groups, templates, template_groups, templates_in_groups, schedules, schedules_with_contacts, schedules_with_contact_groups, jobs, chats, profiles, roles, user_roles, metas
    • Storage bucket attachments
  • Environment variables (see below)

Environment variables

Create nextjs/.env with:

  • NEXT_PUBLIC_SUPABASE_URL
  • NEXT_PUBLIC_SUPABASE_ANON_KEY
  • SERVICE_KEY (Supabase service-role key; used by API routes server-side)
  • APP_SECRET (shared secret allowing service-mode requests)
  • APP_API_ENDPOINT (e.g. http://localhost:3000/api in dev; used to form absolute URLs)
  • ER_ENDPOINT (external messaging endpoint used by job/chat flows)
  • NEXT_PUBLIC_VERCEL_ENV (development | preview | production) used to scope storage paths and URL lifespans

Example:

NEXT_PUBLIC_SUPABASE_URL=https://xxxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=public-anon-key
SERVICE_KEY=service-role-key
APP_SECRET=local-dev-secret
APP_API_ENDPOINT=http://localhost:3000/api
ER_ENDPOINT=https://example.com/er
NEXT_PUBLIC_VERCEL_ENV=development

Install & Run (local)

From the repo root:

cd nextjs
npm i
npm run dev

Then open http://localhost:3000

Docker

The app ships with a production-ready multi-stage Dockerfile under nextjs/.

Useful scripts (run from nextjs/):

  • Build: npm run docker-build
  • Start (fg): npm run docker-start
  • Start (bg): npm run docker-start-bg
  • Stop bg container: npm run docker-stop
  • Cleanup image: npm run docker-cleanup

To use a port other than 3000, adjust docker-start and docker-start-bg in nextjs/package.json.

Project structure

/nextjs
  /components       # Shared UI components
  /pages            # Next.js pages and API routes
    /api            # CRUD + messaging API (server-side, uses SERVICE_KEY)
  Dockerfile        # Multi-stage, output=standalone
  next.config.js    # redirects, images, standalone output
  package.json      # app dependencies and docker scripts
/packages/lib
  /src              # Shared helpers and Supabase client
    APIHelpers.js       # auth() for API routes, role checks via Supabase
    ContactHelpers.js   # formatting/sorting utilities
    MessageHelpers.js   # sendMessage, getAttachmentUrl, message flows
    ScheduleHelpers.js  # fetchSchedules, jobs, deleteScheduleRecord
    TemplateHelpers.js  # fetchTemplates, groups, metas, exports
    supabaseClient.js   # createClient using NEXT_PUBLIC_* envs
  package.json

How it works (high level)

  • Client uses packages/lib/supabaseClient with public anon key for auth and realtime subscriptions.
  • API routes (server-side) create a Supabase client with SERVICE_KEY to perform privileged operations and orchestrate messaging.
  • Role-based access is enforced in API routes via auth() in APIHelpers.js, which validates the bearer token (or APP_SECRET service-mode), fetches user roles from profiles -> user_roles -> roles, and compares the required permission.
  • Messaging and scheduling flows read/write tables (chats, jobs, schedules*) and generate signed URLs for attachments from the attachments bucket. Paths are scoped by NEXT_PUBLIC_VERCEL_ENV (templates/:id.ext or private/:chatId.ext).

Notable pages

  • /dashboard: overview; templates, schedules, jobs summaries
  • /contacts: contacts & groups CRUD, import/export, schedule preview
  • /templates: message bank, groups, metas, exports
  • /schedules: create/edit schedules and view jobs
  • /chats: send messages, view attachments, status updates
  • /users, /roles, /metas: access control and metadata (based on roles)

Development tips

  • Use the correct Node.js version: nvm use
  • Ensure the Supabase schema and storage bucket exist before running
  • Set cookies-based auth: the app stores accessToken from Supabase session in a cookie for API calls
  • Public assets required: public/enurse_logo.png, public/image_404.png

Security notes

  • Keep SERVICE_KEY and APP_SECRET server-only. Do not expose them to the browser.
  • API routes accept either a bearer token (from Supabase auth) or APP_SECRET to enable service-mode operations.

License

Proprietary — internal use only.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment