From 4ccbd28c4fcb0c8eb8f6dc6a54ad7f8e62624f93 Mon Sep 17 00:00:00 2001 From: Matthias Puchstein Date: Thu, 17 Jul 2025 04:18:19 +0200 Subject: [PATCH] expanded and updated `README.md` to include detailed project overview, features breakdown, technical stack, usage guide, project structure, and educational context for improved clarity and documentation quality. Signed-off-by: Matthias Puchstein --- README.md | 311 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 245 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index 2ad678a..16cf88a 100644 --- a/README.md +++ b/README.md @@ -1,90 +1,269 @@ -# REMind (Mockup Demo) +# REMind - Dream Analysis & VR Experience Platform -๐Ÿšง **This is a MOCKUP / DEMO APPLICATION for a university project โ€“ no real backend, AI features, or data storage.** ๐Ÿšง +![Project Status](https://img.shields.io/badge/Status-University%20Project%20Demo-orange) +![License](https://img.shields.io/badge/License-AGPL--3.0-blue) +![TypeScript](https://img.shields.io/badge/TypeScript-95.2%25-blue) -REMind is an interactive, front-end prototype that showcases dream journaling, AI-powered analysis (simulated), and immersive VR demonstrations. Built with React, TypeScript, Vite, and Tailwind CSS, itโ€™s designed for demos and concept validation only. +> **๐Ÿšง IMPORTANT: This is a MOCKUP/DEMO APPLICATION for a university project** +> **No real backend, AI features, or data storage. All functionality is simulated for demonstration purposes.** -## Features (all mockup/demo only) +## Project Overview -- **(Mockup)** Dream Journal - Record dreams as text entries, voice memos, or sketchesโ€”UI only, no persistence. -- **(Mockup)** AI Analysis - Simulated โ€œHere the AI would analyze your dreamโ€ฆโ€ step with instant, hard-coded interpretations, symbol recognition, and emotion tagging. -- **(Mockup)** Personal Archive - Browse and filter past mock entries by date, symbols, emotions, or tags. -- **(Mockup)** Statistics \& Trends - Visualize frequent symbols, emotional patterns, and simulated sleep-cycle correlations using dummy data. -- **(Mockup)** VR Dreamscapes - Enter 3D scenes built with React Three Fiberโ€”explore thematic environments (labyrinths, dark rooms) in browser-based VR mode. -- **Responsive Design** - Works on desktop browsers(design optimized for mobile) and mobile devices. Ideal for QR-code launches at demos. +REMind is an innovative interactive prototype that explores the intersection of dream analysis, artificial intelligence, +and virtual reality. The application demonstrates how modern technology could revolutionize dream journaling and +interpretation through immersive experiences and intelligent analysis. -## Tech Stack +**Project Aim:** To showcase the potential of combining dream journaling with AI-powered analysis and VR visualization, +creating an engaging platform for understanding the subconscious mind and exploring the societal implications of dream +research. -- **Framework:** React + TypeScript -- **Bundler:** Vite -- **Styling:** Tailwind CSS -- **Routing:** React Router Dom -- **Icons:** React Icons -- **3D \& VR:** @react-three/fiber -- **Linting:** ESLint +## โœจ Key Features -## Getting Started +### ๐ŸŒ™ Multi-Modal Dream Recording -> **Note:** This repository contains only a front-end prototype with hard-coded mock data. There is no production backend or AI service. +- **Text Input**: Write detailed dream descriptions with rich formatting +- **Voice Recording**: Record dream narratives with audio transcription +- **Image Upload**: Upload dream sketches, drawings, or related images +- **Biometric Integration**: Simulate EEG, heart rate, and movement data from sleep tracking devices -1. Clone the repo +### ๐Ÿค– AI-Powered Analysis (Simulated) -```bash -git clone https://gitea.puchstein.bayern/mpuchstein/REMind.git -cd REMind -``` +- **Symbol Recognition**: Identify and categorize dream symbols +- **Emotion Detection**: Analyze emotional patterns and mood indicators +- **Interpretation Engine**: Generate personalized dream interpretations +- **Pattern Analysis**: Detect recurring themes and symbols across dreams -2. Install dependencies +### ๐ŸŽฎ VR Dreamscapes -```bash -npm install -``` +- **3D Visualization**: Transform dreams into immersive 3D environments +- **Neural Network Visualization**: Interactive neural network representations for biometric data +- **VR Experience**: WebXR-enabled virtual reality exploration +- **Responsive Controls**: Support for both VR headsets and desktop interaction -3. Run development server +### ๐Ÿ“Š Advanced Analytics -```bash -npm run dev -``` +- **EEG Visualization**: Real-time brainwave pattern charts (Alpha, Beta, Theta, Delta) +- **Vital Signs Monitoring**: Heart rate and HRV trend analysis +- **Movement Tracking**: Sleep movement pattern visualization +- **Statistical Dashboard**: Comprehensive dream pattern analysis -Open `http://localhost:5173` in your browser. 4. Build for production (static demo) +### ๐Ÿ—‚๏ธ Dream Archive & Management -```bash -npm run build -npm run preview -``` +- **Personal Library**: Organized collection of all dream entries +- **Search & Filter**: Advanced filtering by date, symbols, emotions, and tags +- **Social Features**: Share dreams with friends and community +- **Daily Highlights**: Curated dream insights and patterns -## Project Structure +### ๐ŸŒ Community Features + +- **Dream Archive**: Explore categorized dream collections +- **Research Integration**: Live research data visualization +- **Cultural Landscapes**: Dreams categorized by cultural themes +- **Worldwide Events**: Global dream pattern analysis + +## ๐Ÿ› ๏ธ Technology Stack + +### Frontend Framework + +- **React 19.1.0** - Modern React with latest features +- **TypeScript** - Type-safe development +- **Vite 7.0.0** - Fast build tool and development server + +### Styling & UI + +- **Tailwind CSS 4.1.11** - Utility-first CSS framework +- **CSS Variables** - Dynamic theming system +- **Responsive Design** - Mobile-first approach + +### 3D & VR + +- **Three.js 0.178.0** - 3D graphics library +- **@react-three/fiber 9.2.0** - React Three.js renderer +- **@react-three/drei 10.5.1** - Three.js helpers +- **@react-three/xr 6.6.19** - WebXR integration +- **webxr-polyfill 2.0.3** - VR compatibility + +### Data Visualization + +- **D3.js 7.9.0** - Advanced data visualization +- **Custom Chart Components** - EEG, vitals, and movement charts + +### Navigation & Routing + +- **React Router DOM 7.6.3** - Client-side routing +- **React Icons 5.5.0** - Comprehensive icon library + +### Development Tools + +- **ESLint** - Code linting and formatting +- **TypeScript ESLint** - TypeScript-specific linting +- **Vite Plugin React** - React integration + +## ๐Ÿ“ Project Structure ``` -. -โ”œโ”€โ”€ public/ # Static assets +REMind/ +โ”œโ”€โ”€ public/ # Static assets (favicon, etc.) โ”œโ”€โ”€ src/ -โ”‚ โ”œโ”€โ”€ assets/ # Images, fonts -โ”‚ โ”œโ”€โ”€ components/ # Reusable React components -โ”‚ โ”œโ”€โ”€ data/ # Mock data (dream entries, analysis) -โ”‚ โ”œโ”€โ”€ pages/ # Route-driven pages -โ”‚ โ”œโ”€โ”€ types/ # TypeScript types/interfaces -โ”‚ โ”œโ”€โ”€ App.tsx # Root component -โ”‚ โ”œโ”€โ”€ index.css # Tailwind setup -โ”‚ โ””โ”€โ”€ main.tsx # Entry point -โ”œโ”€โ”€ index.html # HTML template -โ”œโ”€โ”€ package.json # Scripts & dependencies -โ”œโ”€โ”€ tsconfig.app.json # TS config for app -โ”œโ”€โ”€ vite.config.ts # Vite config -โ””โ”€โ”€ README.md # This file +โ”‚ โ”œโ”€โ”€ assets/ # Images, logos, fonts +โ”‚ โ”œโ”€โ”€ components/ # Reusable UI components +โ”‚ โ”‚ โ”œโ”€โ”€ DreamCard.tsx # Dream display component +โ”‚ โ”‚ โ”œโ”€โ”€ DreamRecord.tsx # Dream recording interface +โ”‚ โ”‚ โ”œโ”€โ”€ DreamVR.tsx # VR visualization component +โ”‚ โ”‚ โ”œโ”€โ”€ DreamCharts.tsx # Data visualization components +โ”‚ โ”‚ โ”œโ”€โ”€ Navbar.tsx # Navigation component +โ”‚ โ”‚ โ””โ”€โ”€ ... +โ”‚ โ”œโ”€โ”€ data/ # Mock data for demonstration +โ”‚ โ”‚ โ”œโ”€โ”€ MockDreams.ts # Sample dream entries +โ”‚ โ”‚ โ”œโ”€โ”€ MockUsers.ts # User data +โ”‚ โ”‚ โ””โ”€โ”€ ... +โ”‚ โ”œโ”€โ”€ pages/ # Route-driven page components +โ”‚ โ”‚ โ”œโ”€โ”€ Home.tsx # Main dashboard +โ”‚ โ”‚ โ”œโ”€โ”€ Feed.tsx # Dream feed +โ”‚ โ”‚ โ”œโ”€โ”€ DreamPage.tsx # Individual dream view +โ”‚ โ”‚ โ”œโ”€โ”€ Overview.tsx # Landing page +โ”‚ โ”‚ โ””โ”€โ”€ dreamarchive/ # Archive pages +โ”‚ โ”œโ”€โ”€ types/ # TypeScript type definitions +โ”‚ โ”‚ โ”œโ”€โ”€ Dream.ts # Dream data structures +โ”‚ โ”‚ โ””โ”€โ”€ User.ts # User data structures +โ”‚ โ”œโ”€โ”€ utils/ # Utility functions +โ”‚ โ”œโ”€โ”€ styles/ # Styling utilities +โ”‚ โ”œโ”€โ”€ App.tsx # Root component +โ”‚ โ”œโ”€โ”€ main.tsx # Application entry point +โ”‚ โ””โ”€โ”€ index.css # Global styles +โ”œโ”€โ”€ docs/ # Documentation +โ”‚ โ””โ”€โ”€ poster.pdf # Project presentation poster +โ”œโ”€โ”€ package.json # Dependencies and scripts +โ”œโ”€โ”€ tsconfig.app.json # TypeScript configuration +โ”œโ”€โ”€ vite.config.ts # Vite configuration +โ””โ”€โ”€ README.md # This file ``` -## Usage \& Demo +## ๐Ÿš€ Getting Started -- **Start Dream Journal** โ€” click โ€œ๐ŸŒ™ Lass die Magie beginnenโ€ to open the mock dream entry form. -- **AI Analysis** โ€” submit an entry to see the โ€œmockโ€ interpretation card. -- **Browse Archive** โ€” filter mock entries by symbol, emotion, or date. -- **VR Mode** โ€” click VR Demo to load an immersive 3D scene in your browser. +### Prerequisites -**Reminder:** REMind is a design-and-concept prototype only. Enjoy exploring the featuresโ€”no real data or AI integration under the hood! +- Node.js 18+ +- npm or yarn package manager + +### Installation + +1. **Clone the repository** + ```bash + git clone https://gitea.puchstein.bayern/mpuchstein/REMind.git + cd REMind + ``` + +2. **Install dependencies** + ```bash + npm install + ``` + +3. **Start development server** + ```bash + npm run dev + ``` + +4. **Open in browser** + ``` + http://localhost:5173 + ``` + +### Available Scripts + +- `npm run dev` - Start development server +- `npm run build` - Build for production +- `npm run preview` - Preview production build +- `npm run lint` - Run ESLint + +## ๐ŸŽฏ Usage Guide + +### Getting Started + +1. **Landing Page**: Visit the overview page to understand the application concept +2. **Begin Journey**: Click "Lass die Magie beginnen" to start the dream recording experience +3. **Record Dreams**: Use various input methods (text, voice, image, biometric) +4. **AI Analysis**: View simulated AI interpretations and insights +5. **VR Experience**: Explore dreams in virtual reality environments +6. **Archive Exploration**: Browse and filter through dream collections + +### Key Navigation + +- **Home** (`/home`) - Personal dashboard with recent dreams +- **Feed** (`/feed`) - Community dream sharing +- **Record** (`/record`) - Dream input interface +- **Dream Archive** (`/dreamarchive`) - Categorized dream collections +- **Profile** (`/profile`) - User settings and statistics + +### Input Types + +- **Text**: Write detailed dream descriptions +- **Audio**: Record voice memos with transcription +- **Image**: Upload dream-related visuals +- **Chip**: Biometric data from sleep tracking devices + +## ๐Ÿ”ฎ Demo Features + +### Simulated AI Analysis + +- **Symbol Recognition**: Identifies dream symbols like "water," "flying," "animals" +- **Emotion Tagging**: Categorizes emotions as "fear," "joy," "anxiety," "peace" +- **Interpretation**: Generates psychological insights and meanings +- **Pattern Detection**: Highlights recurring themes across dreams + +### VR Visualization + +- **Neural Networks**: Interactive 3D representations of brain activity +- **Dreamscapes**: Immersive environments based on dream content +- **Data Visualization**: 3D charts and graphs for biometric data +- **WebXR Support**: Compatible with VR headsets and desktop browsers + +### Data Analytics + +- **EEG Patterns**: Brainwave analysis during sleep (Alpha, Beta, Theta, Delta) +- **Vital Signs**: Heart rate and heart rate variability trends +- **Movement Data**: Sleep movement and restlessness patterns +- **Statistical Insights**: Long-term pattern analysis and correlations + +## โš ๏ธ Important Notes + +### Assets Not Included + +- **Media Files**: Dream images, audio files, and videos are not included in the repository +- **Mock Data**: All displayed content uses placeholder data for demonstration +- **External Resources**: Some images and media are referenced but not stored in the repository + +### Limitations + +- **No Backend**: All data is stored locally in browser memory +- **No AI Integration**: Analysis results are pre-generated mock responses +- **No Data Persistence**: Data is lost when browser is refreshed +- **Demo Purpose Only**: Not intended for production use + +## ๐ŸŽ“ Educational Context + +This project was developed as a university demonstration to explore: + +- **Human-Computer Interaction**: Innovative interfaces for dream recording +- **Data Visualization**: Advanced techniques for complex data representation +- **Virtual Reality**: Immersive experiences for psychological content +- **AI Integration**: Simulated machine learning for content analysis +- **User Experience**: Intuitive design for sensitive personal data + +## ๐Ÿค Contributing + +This is a university project demo and not actively maintained for production use. However, feedback and suggestions are +welcome for educational purposes. + +## ๐Ÿ“„ License + +This project is licensed under the AGPL-3.0 License - see the LICENSE file for details. + +## ๐Ÿ”— Repository + +[View on Gitea](https://gitea.puchstein.bayern/mpuchstein/REMind) + +--- + +**Disclaimer**: REMind is a prototype demonstration created for educational purposes. All AI features, data analysis, +and interpretations are simulated and should not be used for actual psychological or medical analysis. \ No newline at end of file