Skip to main content
Lens Music is organized as a monorepo containing both the backend API and frontend client applications. This structure allows for shared tooling, consistent versioning, and streamlined development workflows.

​
Repository overview

The root directory contains two main workspaces: 
lens-music/
├── api/              # NestJS backend application
├── client/           # React frontend application
├── dev.sh           # Development startup script
├── .gitignore
└── README.md
Each workspace (api/ and client/) has its own package.json, dependencies, and build configuration, allowing them to be developed and deployed independently.

​
API directory structure

The api/ directory contains the NestJS backend application built with TypeScript and TypeORM.

​
Root level

api/
├── src/                 # Source code
├── dist/               # Compiled JavaScript (generated)
├── node_modules/       # Dependencies (generated)
├── package.json        # API dependencies and scripts
├── tsconfig.json       # TypeScript configuration
├── nodemon.json        # Development server configuration
├── .env               # Environment variables (not committed)
├── .env.example       # Environment variable template
└── README.md

​
Source directory (api/src/)

Contains feature modules organized by domain:
  • artists/ - Artist management endpoints and services
  • auth/ - Authentication and authorization logic
  • labels/ - Record label management
  • lyrics/ - Track lyrics management
  • releases/ - Music release management
  • roles/ - Role and permission management
  • users/ - User account management
Each module typically contains:
  • Controllers (handle HTTP requests)
  • Services (business logic)
  • DTOs (data transfer objects)
TypeORM entity definitions that map to database tables:
  • abstract.entity.ts - Base entity with common fields
  • user.entity.ts - User accounts
  • artist.entity.ts - Artist profiles
  • label.entity.ts - Record labels
  • release.entity.ts - Music releases (albums, singles)
  • track.entity.ts - Individual tracks
  • lyrics.entity.ts - Track lyrics
  • role.entity.ts - User roles
  • permission.entity.ts - System permissions
  • rolePermission.entity.ts - Role-permission mappings
  • releaseArtist.entity.ts - Release-artist relationships
See database schema for detailed entity documentation.
Shared utilities and cross-cutting concerns:
  • decorators/ - Custom TypeScript decorators
  • filters/ - Exception filters for error handling
  • guards/ - Authentication and authorization guards
Application constants and enums:
  • Authentication roles and permissions
  • Artist and user statuses
  • Location data (countries, languages)
Helper functions and utility classes for common operations throughout the application.
TypeScript type definitions:
  • models/ - Interface definitions for data models
  • Common types used across the application
Database seeding scripts to populate initial data for development and testing.
Utility functions and helper methods.
  • app.module.ts - Root application module
  • main.ts - Application entry point
  • data-source.ts - TypeORM data source configuration

​
Client directory structure

The client/ directory contains the React frontend application built with Vite, TypeScript, and Tailwind CSS.

​
Root level

client/
├── src/                    # Source code
├── public/                 # Static assets
├── node_modules/           # Dependencies (generated)
├── dist/                  # Production build (generated)
├── package.json           # Client dependencies and scripts
├── vite.config.ts         # Vite configuration
├── tsconfig.json          # TypeScript configuration
├── components.json        # shadcn/ui configuration
├── postcss.config.js      # PostCSS configuration
├── index.html             # HTML entry point
└── README.md

​
Source directory (client/src/)

Page components organized by feature:
  • landing/ - Landing page components
  • authentication/ - Login and registration pages
  • dashboard/ - Dashboard views
  • artists/ - Artist management pages
  • labels/ - Label management pages
  • releases/ - Release management pages
  • lyrics/ - Lyrics management pages
  • roles/ - Role and permission pages
  • common/ - Shared page components
Reusable React components:
  • ui/ - Base UI components (shadcn/ui)
  • layout/ - Layout components (header, sidebar, footer)
  • inputs/ - Form input components
  • modals/ - Modal dialogs
  • table/ - Table and data grid components
  • graphs/ - Chart and visualization components
  • feedbacks/ - Loading, error, and success states
  • text/ - Typography components
  • landing/ - Landing page specific components
Redux state management:
  • api/ - RTK Query API definitions
  • features/ - Redux slices for different features
  • Store configuration and setup
Custom React hooks:
  • common/ - Shared hooks
  • labels/ - Label-related hooks
  • lyrics/ - Lyrics-related hooks
  • releases/ - Release-related hooks
TypeScript type definitions:
  • models/ - Data model interfaces matching API entities
  • Component prop types
  • Utility types
Frontend constants including:
  • API endpoints
  • Route paths
  • Configuration values
Utility functions for:
  • Data formatting
  • Validation helpers
  • API request helpers
Container components that connect pages to state management.
React Router outlet components for nested routing.
Third-party library configurations and wrappers.
  • App.tsx - Root application component
  • Router.tsx - Application routing configuration
  • main.tsx - Application entry point
  • index.css - Global styles and Tailwind imports

​
Technology stack

​
Backend (API)

NestJS

Progressive Node.js framework for building efficient server-side applications

TypeORM

Object-relational mapper for TypeScript and JavaScript

PostgreSQL

Powerful open-source relational database

JWT

JSON Web Tokens for authentication
Key dependencies:
  • @nestjs/core - NestJS framework core
  • @nestjs/typeorm - TypeORM integration
  • @nestjs/jwt - JWT authentication
  • bcrypt - Password hashing
  • class-validator - Validation decorators
  • pg - PostgreSQL driver

​
Frontend (Client)

React

Popular library for building user interfaces

Vite

Next-generation frontend build tool

Redux Toolkit

State management with Redux made simple

Tailwind CSS

Utility-first CSS framework
Key dependencies:
  • react & react-dom - React library
  • @reduxjs/toolkit - State management
  • react-router-dom - Client-side routing
  • @radix-ui/* - Accessible UI primitives
  • tailwindcss - Styling framework
  • react-hook-form - Form handling
  • recharts - Data visualization

​
Development workflow

1

Start development servers

Run both API and client servers using ./dev.sh or manually in separate terminals.
2

Make changes

Edit files in either api/src/ or client/src/. Both servers support hot reload.
3

Test locally

The API runs on http://localhost:8080 and the client on http://localhost:5173.
4

Build for production

# API
cd api && npm run build

# Client
cd client && npm run build

Development setup

Set up your local development environment

Database schema

Explore the database structure and relationships

Environment variables

Configure your application settings

API reference

API endpoints and usage documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us