lcbp3/specs/00-overview/quick-start.md

Quick Start Guide

Project: LCBP3-DMS Version: 1.5.0 Last Updated: 2025-12-01

---

⚡ 5-Minute Quick Start

This guide will get you up and running with LCBP3-DMS in 5 minutes.

---

👨‍💻 For Developers

Prerequisites

# Required
- Docker 20.10+
- Docker Compose 2.0+
- Git
- Node.js 18+ (for local development)

# Recommended
- VS Code
- Postman or similar API testing tool

Step 1: Clone Repository

git clone <repository-url>
cd lcbp3

Step 2: Setup Environment

# Backend
cp backend/.env.example backend/.env
# Edit backend/.env and set required values

# Frontend
cp frontend/.env.example frontend/.env.local
# Edit frontend/.env.local

Step 3: Start Services

# Start all services with Docker Compose
docker-compose up -d

# Check status
docker-compose ps

Step 4: Initialize Database

# Run migrations
docker exec lcbp3-backend npm run migration:run

# (Optional) Seed sample data
docker exec lcbp3-backend npm run seed

Step 5: Access Application

# Backend API
http://localhost:3000

# Health check
curl http://localhost:3000/health

# Frontend
http://localhost:3001

# API Documentation (Swagger)
http://localhost:3000/api/docs

Step 6: Login

Default Admin Account:

• Username: admin
• Password: Admin@123 (Change immediately!)

---

🧪 For QA/Testers

Running Tests

# Backend unit tests
docker exec lcbp3-backend npm test

# Backend e2e tests
docker exec lcbp3-backend npm run test:e2e

# Frontend tests
docker exec lcbp3-frontend npm test

Test Data

# Reset database to clean state
docker exec lcbp3-backend npm run migration:revert
docker exec lcbp3-backend npm run migration:run

# Load test data
docker exec lcbp3-backend npm run seed

---

🚀 For DevOps

Deploy to Staging

# Build images
docker-compose build

# Push to registry
docker-compose push

# Deploy to staging server
ssh staging-server
cd /app/lcbp3
git pull
docker-compose pull
docker-compose up -d

# Run migrations
docker exec lcbp3-backend npm run migration:run

Deploy to Production

# Backup database first!
./scripts/backup-database.sh

# Deploy with zero-downtime
./scripts/zero-downtime-deploy.sh

# Verify deployment
curl -f https://lcbp3-dms.example.com/health

---

📊 For Project Managers

View Project Status

Documentation:

• Requirements: specs/01-requirements
• Architecture: specs/02-architecture
• Tasks: specs/06-tasks

Metrics:

• Check Monitoring Dashboard (if setup)
• Review Task Board

---

🔍 Common Tasks

Create New Module

# Backend
cd backend
nest g module modules/my-module
nest g controller modules/my-module
nest g service modules/my-module

# Follow backend guidelines
# See: specs/03-implementation/backend-guidelines.md

Create New Migration

# Generate migration from entity changes
docker exec lcbp3-backend npm run migration:generate -- -n MigrationName

# Create empty migration
docker exec lcbp3-backend npm run migration:create -- -n MigrationName

# Run migrations
docker exec lcbp3-backend npm run migration:run

# Revert last migration
docker exec lcbp3-backend npm run migration:revert

View Logs

# All services
docker-compose logs -f

# Specific service
docker logs lcbp3-backend -f --tail=100

# Search logs
docker logs lcbp3-backend 2>&1 | grep "ERROR"

Database Access

# MySQL CLI
docker exec -it lcbp3-mariadb mysql -u root -p

# Run SQL file
docker exec -i lcbp3-mariadb mysql -u root -p lcbp3_dms < script.sql

Redis Access

# Redis CLI
docker exec -it lcbp3-redis redis-cli -a <password>

# Check keys
docker exec lcbp3-redis redis-cli -a <password> KEYS "*"

# Clear cache
docker exec lcbp3-redis redis-cli -a <password> FLUSHDB

---

🐛 Troubleshooting

Backend not starting

# Check logs
docker logs lcbp3-backend

# Common issues:
# 1. Database connection - check DB_HOST in .env
# 2. Redis connection - check REDIS_HOST in .env
# 3. Port conflict - check if port 3000 is free

Database connection failed

# Check if MariaDB is running
docker ps | grep mariadb

# Test connection
docker exec lcbp3-mariadb mysqladmin ping -h localhost

# Check credentials
docker exec lcbp3-backend env | grep DB_

Frontend build failed

# Clear cache and rebuild
docker exec lcbp3-frontend rm -rf .next node_modules
docker exec lcbp3-frontend npm install
docker exec lcbp3-frontend npm run build

Port already in use

# Find process using port
lsof -i :3000

# Kill process
kill -9 <PID>

# Or change port in docker-compose.yml

---

📚 Next Steps

Learn More

1. Architecture - System Architecture
2. Development - Backend Guidelines
3. Deployment - Deployment Guide
4. Decisions - ADR Index

Join the Team

1. Read Contributing Guidelines
2. Pick a task from Backend Tasks
3. Create a branch: git checkout -b feature/my-feature
4. Make changes and write tests
5. Submit Pull Request

---

💡 Tips & Best Practices

Development

• ✅ Always write tests for new features
• ✅ Follow coding guidelines
• ✅ Use TypeScript strict mode
• ✅ Add JSDoc for public APIs
• ✅ Keep Pull Requests small

Git Workflow

# Update main branch
git checkout main
git pull

# Create feature branch
git checkout -b feature/my-feature

# Make commits
git add .
git commit -m "feat: add new feature"

# Push and create PR
git push origin feature/my-feature

Code Review

• Review Backend Guidelines
• Check test coverage
• Verify documentation updated
• Run linter: npm run lint
• Run tests: npm test

---

🆘 Getting Help

Resources

• Documentation: /specs directory
• API Docs: http://localhost:3000/api/docs
• Issue Tracker: [Link to issue tracker]

Contact

• Tech Lead: [Email]
• DevOps: [Email]
• Slack: #lcbp3-dms

---

✅ Checklist for First Day

• Clone repository
• Install prerequisites
• Setup environment variables
• Start Docker services
• Run migrations
• Access backend (http://localhost:3000/health)
• Access frontend (http://localhost:3001)
• Login with default credentials
• Run tests
• Read System Architecture
• Read Backend Guidelines
• Pick first task from Tasks

---

Welcome aboard! 🎉

Version: 1.5.0 Last Updated: 2025-12-01