{"id":30020618,"url":"https://github.com/codedevvv/resonate","last_synced_at":"2026-04-07T18:31:52.139Z","repository":{"id":306541895,"uuid":"1026530237","full_name":"CodeDevvv/Resonate","owner":"CodeDevvv","description":"Your private AI-powered voice diary. A full-stack application built with Next.js, Node.js, Python/FastAPI, and a local LLM.","archived":false,"fork":false,"pushed_at":"2025-07-26T05:08:21.000Z","size":188,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-26T11:20:04.552Z","etag":null,"topics":["ai","expressjs","fastapi","full-stack","llm","nextjs","nodejs","ollama","portfolio-project","python","react","supabase","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CodeDevvv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-26T04:36:03.000Z","updated_at":"2025-07-26T05:08:24.000Z","dependencies_parsed_at":"2025-07-26T11:20:12.953Z","dependency_job_id":"c06b332e-33a0-4a44-ad7f-a6a6b3208dab","html_url":"https://github.com/CodeDevvv/Resonate","commit_stats":null,"previous_names":["codedevvv/resonate"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/CodeDevvv/Resonate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeDevvv%2FResonate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeDevvv%2FResonate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeDevvv%2FResonate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeDevvv%2FResonate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CodeDevvv","download_url":"https://codeload.github.com/CodeDevvv/Resonate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeDevvv%2FResonate/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269005891,"owners_count":24343408,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-06T02:00:09.910Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","expressjs","fastapi","full-stack","llm","nextjs","nodejs","ollama","portfolio-project","python","react","supabase","typescript"],"created_at":"2025-08-06T02:02:31.926Z","updated_at":"2026-04-07T18:31:52.115Z","avatar_url":"https://github.com/CodeDevvv.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RESONATE\n\n![Next JS](https://img.shields.io/badge/Next-black?style=for-the-badge\u0026logo=next.js\u0026logoColor=white)\n![NodeJS](https://img.shields.io/badge/node.js-6DA55F?style=for-the-badge\u0026logo=node.js\u0026logoColor=white)\n![Express.js](https://img.shields.io/badge/express.js-%23404d59.svg?style=for-the-badge\u0026logo=express\u0026logoColor=%2361DAFB)\n![FastAPI](https://img.shields.io/badge/FastAPI-005571?style=for-the-badge\u0026logo=fastapi)\n![Google Gemini](https://img.shields.io/badge/Google%20Gemini-8E75B2?style=for-the-badge\u0026logo=google%20gemini\u0026logoColor=white)\n![Ollama](https://img.shields.io/badge/Ollama-000000?style=for-the-badge\u0026logo=ollama\u0026logoColor=white)\n![TanStack Query](https://img.shields.io/badge/-TanStack%20Query-FF4154?style=for-the-badge\u0026logo=react-query\u0026logoColor=white)\n![LLM](https://img.shields.io/badge/AI-LLM-blue?style=for-the-badge)\n![Upstash Redis](https://img.shields.io/badge/Upstash_Redis-00E676?style=for-the-badge\u0026logo=redis\u0026logoColor=white)\n![Groq](https://img.shields.io/badge/Groq-F55036?style=for-the-badge\u0026logo=groq\u0026logoColor=white)\n\nYour private, AI-powered voice diary -\u003e record, reflect, and rediscover yourself through sound.\n\n## 📖 Overview\n\nResonate is a full-stack web application designed to be a modern, intelligent journaling experience. Users can record audio diary entries which are transcribed and analyzed by a Hybrid AI Engine. The application leverages a microservice-inspired architecture where a Node.js backend handles business logic, API security, and automated maintenance, while a detached Python FastAPI service handles heavy ML computation asynchronously.\n\nThe system is built for ultimate flexibility and protection. It supports both **Local AI** (Ollama + local Whisper) for offline, privacy-focused users, and **Cloud AI** (Google Gemini + Groq) for high-speed analysis. The API layer is strictly protected by Upstash Serverless Redis to prevent abuse and manage rate limits effectively.\n\n## ✨ Core Features\n\n* **🎙️ Voice Recording:** Intuitive interface to record, preview, and upload audio entries.\n* **⚡ Real-Time Architecture:**\n    * **Fire-and-Forget Processing:** The user is never blocked waiting for AI. Uploads return immediately while analysis runs in the background using FastAPI's BackgroundTasks and asyncio.\n    * **Live Notifications:** Integrated Socket.io pushes real-time updates to the client when analysis completes, updating the UI instantly without page reloads.\n* **🧠 Hybrid AI Analysis \u0026 Transcription:**\n    * **Flexible Backend:** Seamlessly switch between Local LLMs (Ollama) or Cloud AI (Google Gemini) via environment variables.\n    * **High-Speed Transcription:** Toggle between local Whisper processing or ultra-fast external transcription using **Groq's API (whisper-large-v3)**.\n    * **Adaptive Prompting:** Uses \"One-Shot\" prompting for Gemini and \"Chain of Thought\" (4 separate calls) for local models to ensure high accuracy.\n* **🛡️ API Protection \u0026 Rate Limiting:**\n    * Integrated **Upstash Serverless Redis** with Node.js to strictly govern API usage without consuming local server memory.\n    * Tiered rate limiting tied to Clerk User IDs:\n      * **Standard DB Limits:** 100 requests per minute.\n      * **AI Burst Limits:** 3 AI requests per minute.\n      * **AI Daily Quota:** 20 AI processing requests per 24 hours.\n* **🎯 Smart Goal Detection:** The AI intelligently identifies potential life goals mentioned in your audio and suggests adding them to your tracker.\n* **📊 Analytics Dashboard:** Server-side aggregated visualizations using SQL functions for maximum performance:\n    * **Mood Trend Line:** Track emotional changes over time.\n    * **Emotion Heatmap:** Calendar view of daily dominant emotions.\n    * **Topic Frequency:** Analysis of most discussed themes.\n* **🔐 Enterprise-Grade Security:**\n    * **Encryption at Rest:** All sensitive text (transcripts, summaries, reflections) is encrypted at the application layer before storage.\n    * **Row Level Security (RLS):** Supabase policies ensure strict data isolation between users—users can only access their own data.\n* **🚀 Performance:**\n    * **TanStack Query:** All API calls utilize useQuery and useMutation for aggressive caching, optimistic updates, and background re-fetching.\n    * **Server-Side Aggregation:** Heavy analytics calculations are offloaded to Postgres functions via schema_logic.sql, keeping the API lightweight.\n\n## 🏗️ Technical Architecture\n\nResonate uses an Event-Driven, Asynchronous Architecture to handle heavy AI workloads without compromising user experience.\n\n```mermaid\nsequenceDiagram\n    participant User as Frontend (Next.js)\n    participant Node as Backend (Express)\n    participant DB as Supabase (Postgres)\n    participant Python as ML Service (FastAPI)\n    \n    User-\u003e\u003eNode: 1. Upload Audio\n    Node-\u003e\u003eDB: 2. Save File \u0026 Create Entry (Status: Processing)\n    Node-\u003e\u003ePython: 3. Dispatch Analysis Job (Fire \u0026 Forget)\n    Node--\u003e\u003eUser: 4. Return 200 OK (Immediate)\n    \n    Note over Python: Background Tasks (Async)\n    Python-\u003e\u003ePython: 5. Transcribe (Whisper)\n    Python-\u003e\u003ePython: 6. Analyze (Gemini/Ollama)\n    \n    Python-\u003e\u003eNode: 7. Webhook POST /ai-result\n    Node-\u003e\u003eDB: 8. Update Entry (Encrypted Data)\n    Node-\u003e\u003eUser: 9. Socket Emit (Real-time Update)\n\n```\n\n## Folder Structure\n\n```text\nResonate\n├── LICENSE\n├── README.md\n├── resonate-backend\n│   ├── Backend-ML              # Python FastAPI Service\n│   │   ├── main.py             # Entry point \u0026 Endpoints\n│   │   ├── requirements.txt\n│   │   └── utils\n│   │       ├── ai_service.py   # LLM Logic (Gemini/Ollama)\n│   │       └── helperFunction.py\n│   └── Backend-Node            # Node.js Express Service\n│       ├── controllers/        # Business Logic\n│       │   ├── entryController.js\n│       │   ├── goalController.js\n│       │   ├── insightController.js\n│       │   ├── quoteController.js\n│       │   └── webhookController.js\n|       ├── jobs/\n|       |   └── storageCleanUp.js # Cron Job\n|       ├── middleware/\n|       |   └── rateLimiter.js # API Rate Limiters\n│       ├── routes/             # API Routes\n│       │   ├── entryRoutes.js\n│       │   ├── goalRoutes.js\n│       │   ├── insightRoutes.js\n│       │   ├── quoteRoutes.js\n│       │   └── webhookRoutes.js\n│       ├── server.js\n│       └── utils\n│           ├── config.js\n│           └── encryption.js   # AES Encryption Logic\n├── resonate-frontend           # Next.js Application\n│   ├── src\n│   │   ├── app                 # App Router\n│   │   ├── components          # Shadcn UI \u0026 Custom Components\n│   │   ├── hooks               # Custom React Query Hooks\n│   │   ├── lib                 # Utilities \u0026 Socket Client\n│   │   └── ...\n└── schema_logic.sql            # Database Triggers \u0026 Functions\n\n```\n\n## 🛠️ Database Logic \u0026 Automation\n\nResonate uses a combination of server-side Postgres functions and Node.js scheduled tasks to maintain performance and data integrity.\n\n* **Server-Side Analytics (`get_insights`):**\n    * Instead of fetching thousands of rows to Node.js to calculate averages, we call a single SQL RPC function.\n    * It computes Heatmaps, Mood Charts, and Topic frequencies directly within the Postgres engine and returns a single, pre-calculated JSON object.\n\n* **Automated Storage Cleanup (Orphan Sweeper):**\n    * *Note:* Due to Supabase policy restrictions on executing direct SQL deletes on storage buckets via triggers, the previous database-level cleanup triggers were dropped.\n    * **Node.js Cron Job:** We now utilize a dedicated scheduled task (`jobs/storageCleanUp.js`) using the `cron` library on the Express backend.\n    * **Execution:** Runs every Sunday at 3:00 AM (`0 3 * * 0`).\n    * **Logic:** It fetches all file paths currently sitting in the Supabase storage bucket and cross-references them against a `Set` of `audio_path` values actively linked to user Diary Entries in the database. Any file in storage that does not exist in the database records is identified as an orphan and permanently deleted, ensuring zero wasted cloud storage costs.\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n* Bun (v1.0+)\n* Python (v3.10+)\n* Supabase Project\n* Clerk Account\n* Ollama (Optional, for local AI)\n\n### 1. Environment Setup\n\nClone the repo and configure environment variables. Refer to `.env.example`\n\n```bash\ngit clone https://github.com/CodeDevvv/Resonate.git\ncd resonate\n```\n\n### 2. Database Setup\n\n1. Go to your Supabase SQL Editor.\n2. Run the contents of `schema_logic.sql`. This creates the Tables, Enums, Triggers, and Analytics Functions required for the app to function.\n\n### 3. AI Model Setup \u0026 Transcription\n\nThe application can toggle seamlessly between Cloud and Local processing simply by changing the `USE_LOCAL_LLM` flag in your environment variables.\n\n**Option A: Cloud AI (Google Gemini + Groq Transcription)**\nThis is the recommended setup for the fastest processing times and lowest server memory usage.\n\n1. Get an API Key from [Google AI Studio](https://aistudio.google.com/) and the [Groq Console](https://console.groq.com/).\n2. Set the following in your `Backend-ML/.env`:\n```env\nUSE_LOCAL_LLM=False\nRESONATE_GEMINI_KEY=your_gemini_api_key\nGROQ_WHISPER_KEY=your_groq_api_key\nLLM_MODEL_ID=gemini-1.5-pro-latest # Or your preferred Gemini model\n# LLM_API_URL= # \n```\n### 3.5 Rate Limiting Setup (Upstash)\n1. Create a free Serverless Redis database on [Upstash](https://upstash.com/).\n2. Copy the Redis URL and add it to `Backend-Node/.env`:\n```bash\nUPSTASH_REDIS_URL=\"rediss://default:your_password@your_url.upstash.io:6379\"\n```\n\n### 4. Run the Application\n\n**Step 1: Start ML Backend (Python)**\nHandles Transcription \u0026 Intelligence.\n\n```bash\ncd resonate-backend/Backend-ML\npip install -r requirements.txt\nuvicorn main:app --reload --port 8000\n```\n\n**Step 2: Start API Backend (Node.js)**\nHandles Database, Auth, and Webhooks.\n\n```bash\ncd resonate-backend/Backend-Node\nbun install\nbun run server\n```\n\n**Step 3: Start Frontend (Next.js)**\nThe User Interface.\n\n```bash\ncd resonate-frontend\nbun install\nbun run dev\n```\n\nVisit `http://localhost:3000` to start recording.\n\n## 🧩 Feature to Tech Mapping\n\n| Feature | Tech Stack |\n| --- | --- |\n| **Frontend Caching** | TanStack Query (Stale-while-revalidate strategy) |\n| **Real-time Status** | Socket.io (Event-driven updates) |\n| **DB, Storage** | Supabase (PostgreSQL + Triggers) |\n| **Rate Limiting** | Upstash Serverless Redis + Express Rate Limit |\n| **Transcription** | Groq API (whisper-large-v3) or Local OpenAI Whisper |\n| **LLM Orchestration** | FastAPI (Background Tasks) |\n| **Analytics** | RPC |\n| **CRON** | node-cron (clean up db storage) |\n\n## 📜 License\n\nThis project is licensed under the MIT License. See the LICENSE file for the full text.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodedevvv%2Fresonate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodedevvv%2Fresonate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodedevvv%2Fresonate/lists"}