Guides & Resources
Getting Started
Prerequisites
- Node.js 20.x or higher
- PostgreSQL 15.x
- Redis 7.x (optional for development)
- Docker (optional)
Installation
git clone https://github.com/example/ecommerce-platform.git
cd ecommerce-platform
npm install
cp .env.example .env
# Edit .env with your database credentials
npm run db:migrate
npm run dev
Verification
After starting the server, verify installation:
- ✅ Server running at
http://localhost:3000
- ✅ API health check:
curl http://localhost:3000/api/health
- ✅ Database migrations applied:
npm run db:status
How-To Guides
How to Add a New Product
- Login as admin:
POST /api/auth/login with admin credentials
- Get JWT token from response
- Create product:
curl -X POST http://localhost:3000/api/products \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"name": "Product Name",
"description": "Product Description",
"price": 29.99,
"stock_quantity": 100,
"category": "Electronics"
}'
- Verify product created:
GET /api/products/:id
How to Test API Endpoints
- Start development server:
npm run dev
- Run tests:
- All tests:
npm test
- E2E tests only:
npm run test:e2e
- Integration tests:
npm run test:integration
- Unit tests:
npm run test:unit
- View coverage report:
npm run test:coverage
How to Deploy to Production
- Build Docker image:
docker build -t ecommerce-api .
- Push to registry:
docker push ecommerce-api:latest
- Update ECS task definition with new image
- Deploy via GitHub Actions (automatic on merge to main)
- Verify deployment: Check CloudWatch logs for startup
Best Practices
Code Style
- Follow KISS/YAGNI/DRY principles
- Use TypeScript for type safety
- Keep functions small and focused (< 30 lines)
- Use meaningful variable names (no single letters except loops)
Testing Approach
- Follow Risk-Based Testing (Priority ≥ 15 scenarios MUST be tested)
- E2E tests (2-5 per Story): Critical user flows
- Integration tests (3-8 per Story): API endpoints
- Unit tests (5-15 per Story): Business logic only
- Test OUR code, not frameworks (Express already tested)
Design Patterns
- Layered architecture: Controller → Service → Repository
- Dependency Injection for testability
- Repository pattern for database access
- DTO (Data Transfer Objects) for API requests/responses
Troubleshooting
Database Connection Errors
Problem: "Unable to connect to PostgreSQL"
Solution:
- Check PostgreSQL is running:
pg_isready
- Verify .env credentials match database
- Check firewall allows port 5432
Port Already in Use
Problem: "Port 3000 is already in use"
Solution:
- Change PORT in .env to different port (e.g., 3001)
- Or kill process using port:
lsof -ti:3000 | xargs kill
JWT Token Expired
Problem: "401 Unauthorized - Token expired"
Solution:
- Use refresh token:
POST /api/auth/refresh with refresh token
- Get new access token from response
- Tokens expire after 15 minutes for security
Tests Failing Randomly
Problem: Tests pass locally but fail in CI
Solution:
- Check test isolation (no shared state between tests)
- Use transactions in tests (rollback after each test)
- Seed database with consistent test data
Contributing Guidelines
- Fork the repository
- Create branch:
git checkout -b feature/your-feature
- Write code following style guide
- Write tests: All new code must have tests (85%+ coverage)
- Run tests:
npm test (all must pass)
- Commit:
git commit -m "Add your feature"
- Push:
git push origin feature/your-feature
- Submit PR with description of changes