# Quixotic Project Structure

## Directory Layout
```
quixotic/
├── src/                    # Backend source code
│   ├── server.js          # Main Express server (entry point)
│   ├── bot.js             # Telegram bot logic
│   ├── youtube.js         # YouTube service (YouTubeService class)
│   └── database.js        # SQLite database wrapper (Database class)
├── public/                # Static frontend assets
│   ├── index.html         # Main Web App interface
│   ├── style.css          # Styles for the Web App
│   └── script.js          # Client-side JavaScript
├── database/              # SQLite database files
├── downloads/             # Generated MP3 files (created at runtime)
├── .serena/               # Serena configuration
├── .claude/               # Claude Code configuration
├── package.json           # Project configuration and dependencies
├── yarn.lock              # Yarn lockfile
├── .env.example           # Environment variables template
├── .gitignore             # Git ignore rules
├── README.md              # Project documentation
├── WORKLOG.md             # Development log
├── YOUTUBE_SETUP.md       # YouTube setup instructions
└── .mcp.json              # MCP configuration
```

## Key Files and Their Roles

### Backend (src/)
- **server.js**: Main Express server with API endpoints:
  - `POST /api/search` - Search YouTube videos
  - `POST /api/convert` - Convert video to MP3
  - `GET /downloads/:filename` - Serve MP3 files
  - `GET /health` - Health check endpoint

- **youtube.js**: YouTube service handling video search and metadata
- **database.js**: SQLite database wrapper with tables for users, search_history, downloads
- **bot.js**: Telegram bot integration

### Frontend (public/)
- **index.html**: Telegram Web App interface
- **script.js**: Client-side logic for search and conversion
- **style.css**: Web App styling

## API Architecture
RESTful API with Express.js serving both the Web App and API endpoints. The app uses SQLite for persistent storage and FFmpeg for audio processing.