🎵 LofiStudio

LofiStudio is an immersive, customizable productivity workspace designed to help you focus, relax, or work efficiently. It combines high-quality ambient sounds, real-time widgets, and a dynamic 3D glassmorphic interface into a unified "Studio" experience.

✨ What's New in V2?

The new Studio V2 architecture brings significant improvements:

• Real-time Data Integrations: Live Weather (OpenWeather/Open-Meteo), World Time, and dynamic Radio Browser.
• Robust Audio Engine: Gapless playback, bandwidth optimization (metadata only), and error recovery.
• Responsive Layouts: Smart 2x3 and 3x3 grids that adapt seamlessly from desktop to mobile.
• Widgets Ecosystem: A growing collection of productivity tools (Pomodoro, Tasks, Dictionary, Quotes).
• Vercel Serverless Optimized: Stateless architecture with selective persistence.

---

📚 Documentation

Detailed technical documentation is available in the docs/ directory:

• 🏗️ Architecture Overview: Deep dive into the V2 system, providers, and state management.
• 🧩 Widget System: How the grid works, creating new widgets, and layout persistence.
• 🔊 Audio Engine: Explanation of the Web Audio API implementation and mixing logic.
• 🌍 Real Data & APIs: List of external services, environment variables, and integration details.

---

🚀 Getting Started

Prerequisites

• Node.js 18+
• npm or pnpm
• (Optional) PostgreSQL (Neon) for cloud sync features.

Installation

1. Clone the repository

   git clone https://github.com/your-username/LofiStudio.git
   cd LofiStudio

2. Install dependencies

   npm install

3. Configure Environment Variables Create a .env.local file based on .env.example:

   # Essential APIs
   UNSPLASH_ACCESS_KEY=your_unsplash_key
   OPENWEATHER_API_KEY=your_weather_key
   YOUTUBE_API_KEY=your_youtube_key

   See Real Data Docs for full configuration details.

4. Run Development Server

   npm run dev

   Open http://localhost:3000 to view the studio.

---

🛠️ Technology Stack

• Framework: Next.js 14 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS, Framer Motion, Radix UI (Primitives)
• State Management: Zustand
• Database: Drizzle ORM + PostgreSQL
• Authentication: NextAuth.js

---

📂 Project Structure

LofiStudio/
├── app/
│   ├── components/
│   │   ├── StudioV2/       # Core layout and logic
│   │   ├── WidgetsV2/      # Individual widget components
│   │   ├── WidgetGrid/     # Drag-and-drop system
│   │   └── SettingsV2/     # Configuration panels
│   ├── studio/             # Main application route
│   └── api/                # Server-side API proxies
├── lib/
│   ├── audio/              # AudioManager engine
│   ├── stores/             # Global Zustand stores
│   └── constants/          # Static configuration
├── docs/                   # Technical documentation
└── public/                 # Static assets (sounds, icons)

---

🤝 Contributing

Contributions are welcome! Please read our architecture guidelines in docs/ before submitting a Pull Request.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

Distributed under the MIT License. See LICENSE for more information.

---

Made with ❤️ for focus and relaxation.