MusiqasiQ - Agent Documentation

What is MusiqasiQ?

A React-based web application that visualizes artist similarity relationships through interactive force-directed graphs. Integrates with Last.fm API and provides an engaging interface for exploring music artist connections.

Tech Stack

Frontend: React 18 + TypeScript + Vite + Tailwind CSS + shadcn/ui + D3.js
Services: Effect library for typed, composable service architecture
API Caching: Cloudflare Workers (optional local development)
State: React hooks for local state, Effect runtime for service operations
Routing: React Router DOM

Project Structure

musiqasik/
├── src/
│   ├── components/         # React components
│   │   ├── ForceGraph/     # D3.js graph visualization (refactored into hooks)
│   │   └── ui/             # shadcn/ui components
│   ├── hooks/              # React hooks (useLastFm, useSimilarArtists, etc.)
│   ├── services/           # Effect services (LastFm, Database, Graph, Config)
│   ├── integrations/       # External service clients
│   ├── lib/                # Utilities and error types
│   ├── pages/              # Route pages
│   └── types/              # TypeScript type definitions
├── e2e/                    # Playwright E2E tests
└── public/                 # Static assets

Getting Started

Setup: Copy
```
.env.example
```
to
```
.env
```
and add your Last.fm API key
Development:
```
bun run dev
```
starts server on port 8080
Building:
```
bun run build
```
for production
Testing:
```
bun run test
```
for unit tests,
```
bun run test:e2e
```
for E2E tests
Linting:
```
bun run lint
```
runs Biome

Architecture Overview

Data Flow: Search → useLastFm hook → Effect runtime → LastFmService → Last.fm API → Graph
Graph Visualization: D3.js force simulation with modular hooks (
```
ForceGraph/hooks/
```
)
Caching: Optional Cloudflare Workers caching
State: URL params for shareable graphs, React hooks for UI state
Service Layer: Effect-based services with proper dependency injection

Key Services (in

src/services/

)

ConfigService: Environment configuration (API keys, DB URLs)
LastFmService: Last.fm API integration (search, artist info, similar artists)
DatabaseService: Cloudflare KV operations (artist caching)
GraphService: BFS graph building algorithm

How to Work on This Project

Before Starting

Read relevant documentation files based on your task
Study existing code patterns in similar components/files
Check
```
package.json
```
for available scripts

Documentation Files (Progressive Disclosure)

Consult these files for detailed information:

```
agent_docs/development-workflow.md
```
- Setup, scripts, environment
```
agent_docs/architecture-patterns.md
```
- System design and data flow
```
agent_docs/code-conventions.md
```
- Patterns to follow (learn from existing code)
```
agent_docs/common-tasks.md
```
- Step-by-step guides for common operations
```
agent_docs/troubleshooting.md
```
- Debugging and common issues
```
agent_docs/effect.md
```
- Effect library patterns and API reference

Key Principles

Follow existing patterns: Study similar components before creating new ones
Use TypeScript: Interfaces in
```
src/types/
```
, optional properties with
```
?
```
Use Effect for services: Services use Effect library for composable, typed operations
Style with Tailwind: Use
```
cn()
```
utility for conditional classes (
```
src/lib/utils.ts
```
)
Handle errors: AppError types in
```
src/lib/errors.ts
```
, toast notifications for user feedback
Write tests: Unit tests with Vitest, E2E tests with Playwright

Important Notes

TypeScript strict mode is disabled (
```
tsconfig.app.json
```
)
Path aliases:
```
@/
```
maps to
```
./src/
```
(
```
vite.config.ts
```
)
Environment variables: Must be prefixed with
```
VITE_
```
for client-side access
Caching optional: App works without Cloudflare Workers using Last.fm directly

Testing

```
bun run test
```
- Unit tests (hooks, utilities, services)
```
bun run test:e2e
```
- E2E tests (Playwright)
```
bun run test:coverage
```
- Coverage report

Tech Stack

Frontend: React 18 + TypeScript + Vite + Tailwind CSS + shadcn/ui + D3.js

Services: Effect library for typed, composable service architecture

API Caching: Cloudflare Workers (optional local development)

State: React hooks for local state, Effect runtime for service operations

Routing: React Router DOM

Project Structure

musiqasik/
├── src/
│   ├── components/         # React components
│   │   ├── ForceGraph/     # D3.js graph visualization (refactored into hooks)
│   │   └── ui/             # shadcn/ui components
│   ├── hooks/              # React hooks (useLastFm, useSimilarArtists, etc.)
│   ├── services/           # Effect services (LastFm, Database, Graph, Config)
│   ├── integrations/       # External service clients
│   ├── lib/                # Utilities and error types
│   ├── pages/              # Route pages
│   └── types/              # TypeScript type definitions
├── e2e/                    # Playwright E2E tests
└── public/                 # Static assets

Architecture Overview

Data Flow: Search → useLastFm hook → Effect runtime → LastFmService → Last.fm API → Graph

Graph Visualization: D3.js force simulation with modular hooks (

ForceGraph/hooks/

)

Caching: Optional Cloudflare Workers caching

State: URL params for shareable graphs, React hooks for UI state

Service Layer: Effect-based services with proper dependency injection

ConfigService: Environment configuration (API keys, DB URLs)

LastFmService: Last.fm API integration (search, artist info, similar artists)

DatabaseService: Cloudflare KV operations (artist caching)

GraphService: BFS graph building algorithm

How to Work on This Project

Read relevant documentation files based on your task

Study existing code patterns in similar components/files

Check

package.json

for available scripts

Consult these files for detailed information:

agent_docs/development-workflow.md

- Setup, scripts, environment

agent_docs/architecture-patterns.md

- System design and data flow

agent_docs/code-conventions.md

- Patterns to follow (learn from existing code)

agent_docs/common-tasks.md

- Step-by-step guides for common operations

agent_docs/troubleshooting.md

- Debugging and common issues

agent_docs/effect.md

- Effect library patterns and API reference

Follow existing patterns: Study similar components before creating new ones

Use TypeScript: Interfaces in

src/types/

, optional properties with

Use Effect for services: Services use Effect library for composable, typed operations

Style with Tailwind: Use

cn()

utility for conditional classes (

src/lib/utils.ts

)

Handle errors: AppError types in

src/lib/errors.ts

, toast notifications for user feedback

Write tests: Unit tests with Vitest, E2E tests with Playwright

TypeScript strict mode is disabled (

tsconfig.app.json

)

Path aliases:

@/

maps to

./src/

(

vite.config.ts

)

Environment variables: Must be prefixed with

VITE_

for client-side access

Caching optional: App works without Cloudflare Workers using Last.fm directly

MusiqasiQ - Agent Documentation

What is MusiqasiQ?

Tech Stack

Project Structure

Getting Started

Architecture Overview

Key Services (in
`src/services/`
)

How to Work on This Project

Before Starting

Documentation Files (Progressive Disclosure)

Key Principles

Important Notes

Testing

Related Skills

Markdown Converter

Nano Banana Pro

1password

MusiqasiQ - Agent Documentation

What is MusiqasiQ?

Tech Stack

Project Structure

Getting Started

Architecture Overview

Key Services (in
`src/services/`
)

How to Work on This Project

Before Starting

Documentation Files (Progressive Disclosure)

Key Principles

Important Notes

Testing