398 lines
9.2 KiB
Markdown
398 lines
9.2 KiB
Markdown
# 🏥 Claim Guard Backend
|
|
|
|
> **NestJS application for managing ICD-9 and ICD-10 medical codes with Excel import functionality**
|
|
|
|
[](https://nestjs.com/)
|
|
[](https://www.typescriptlang.org/)
|
|
[](https://www.postgresql.org/)
|
|
[](https://www.docker.com/)
|
|
[](https://www.prisma.io/)
|
|
|
|
## ✨ Features
|
|
|
|
- 🏥 **ICD Code Management** - Import and manage ICD-9 and ICD-10 medical codes
|
|
- 📊 **Excel Import** - Read data from Excel files and store in PostgreSQL
|
|
- 🔍 **Search & Filter** - Search codes by category, code, or display text
|
|
- 🌐 **REST API** - Full REST API with Swagger documentation
|
|
- 📄 **Pagination** - Built-in pagination for large datasets
|
|
- 🐳 **Docker Ready** - PostgreSQL with pgvector extension
|
|
- 🔄 **Database Migrations** - Prisma migration system
|
|
- ✅ **Input Validation** - Type-safe DTOs with validation
|
|
- 📚 **API Documentation** - Interactive Swagger UI
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js 18+
|
|
- Docker & Docker Compose
|
|
- Git
|
|
|
|
### 1. Clone & Install
|
|
|
|
```bash
|
|
git clone <repository-url>
|
|
cd claim-guard-be
|
|
npm install
|
|
```
|
|
|
|
### 2. Start Database
|
|
|
|
```bash
|
|
# Start PostgreSQL with pgvector
|
|
docker-compose up -d
|
|
|
|
# Verify database is running
|
|
docker-compose ps
|
|
```
|
|
|
|
### 3. Setup Environment
|
|
|
|
```bash
|
|
# Copy environment template (edit as needed)
|
|
copy .env.example .env
|
|
|
|
# Update DATABASE_URL in .env:
|
|
DATABASE_URL=postgresql://postgres:postgres123@localhost:5432/claim_guard
|
|
```
|
|
|
|
### 4. Run Migrations
|
|
|
|
```bash
|
|
# Apply database schema
|
|
npx prisma migrate deploy
|
|
|
|
# Generate Prisma client
|
|
npx prisma generate
|
|
```
|
|
|
|
### 5. Start Application
|
|
|
|
```bash
|
|
# Development mode
|
|
npm run start:dev
|
|
|
|
# Production mode
|
|
npm run build
|
|
npm run start:prod
|
|
```
|
|
|
|
### 6. Access Services
|
|
|
|
- **API**: http://localhost:3000
|
|
- **Swagger Docs**: http://localhost:3000/docs
|
|
- **Health Check**: http://localhost:3000/health
|
|
|
|
## 📚 API Endpoints
|
|
|
|
### ICD Management
|
|
|
|
| Method | Endpoint | Description |
|
|
| ------ | ----------------- | -------------------------------- |
|
|
| `POST` | `/icd/import` | Import ICD data from Excel files |
|
|
| `GET` | `/icd/search` | Search ICD codes with filters |
|
|
| `GET` | `/icd/statistics` | Get database statistics |
|
|
|
|
### Health & Monitoring
|
|
|
|
| Method | Endpoint | Description |
|
|
| ------ | --------------- | ----------------------------- |
|
|
| `GET` | `/health` | Application health check |
|
|
| `GET` | `/health/ready` | Readiness probe |
|
|
| `GET` | `/health/live` | Liveness probe |
|
|
| `GET` | `/docs` | Interactive API documentation |
|
|
|
|
### Example Usage
|
|
|
|
```bash
|
|
# Import ICD data
|
|
curl -X POST http://localhost:3000/icd/import
|
|
|
|
# Search for diabetes codes
|
|
curl "http://localhost:3000/icd/search?search=diabetes&page=1&limit=10"
|
|
|
|
# Get statistics
|
|
curl http://localhost:3000/icd/statistics
|
|
|
|
# Health check
|
|
curl http://localhost:3000/health
|
|
```
|
|
|
|
## 🐳 Docker Setup
|
|
|
|
### Database Only (Recommended)
|
|
|
|
```bash
|
|
# Start PostgreSQL with pgvector
|
|
docker-compose up -d
|
|
|
|
# Stop database
|
|
docker-compose down
|
|
|
|
# Reset database (deletes all data!)
|
|
docker-compose down -v
|
|
```
|
|
|
|
### Connection Details
|
|
|
|
```env
|
|
DATABASE_URL=postgresql://postgres:postgres123@localhost:5432/claim_guard
|
|
Host: localhost
|
|
Port: 5432
|
|
Database: claim_guard
|
|
Username: postgres
|
|
Password: postgres123
|
|
```
|
|
|
|
### Verify pgvector Extension
|
|
|
|
```bash
|
|
docker-compose exec postgres psql -U postgres -d claim_guard -c "SELECT name, default_version, installed_version FROM pg_available_extensions WHERE name = 'vector';"
|
|
```
|
|
|
|
## 🗂️ Database Schema
|
|
|
|
### IcdCode Model
|
|
|
|
```prisma
|
|
model IcdCode {
|
|
id String @id @default(uuid())
|
|
code String @unique
|
|
display String
|
|
version String
|
|
category String // "ICD9" or "ICD10"
|
|
createdAt DateTime @default(now())
|
|
updatedAt DateTime @updatedAt
|
|
|
|
@@map("icd_codes")
|
|
}
|
|
```
|
|
|
|
### Migration Commands
|
|
|
|
```bash
|
|
# Check migration status
|
|
npx prisma migrate status
|
|
|
|
# Create new migration
|
|
npx prisma migrate dev --name description
|
|
|
|
# Deploy to production
|
|
npx prisma migrate deploy
|
|
|
|
# Reset database (development)
|
|
npx prisma migrate reset
|
|
```
|
|
|
|
## ⚙️ Environment Configuration
|
|
|
|
### Development
|
|
|
|
```env
|
|
NODE_ENV=development
|
|
PORT=3000
|
|
DATABASE_URL=postgresql://postgres:postgres123@localhost:5432/claim_guard
|
|
CORS_ORIGINS=http://localhost:3000,http://localhost:3001
|
|
ENABLE_DOCS=true
|
|
DEBUG=true
|
|
LOG_LEVEL=debug
|
|
```
|
|
|
|
### Production
|
|
|
|
```env
|
|
NODE_ENV=production
|
|
PORT=3000
|
|
DATABASE_URL=postgresql://user:pass@host:5432/db
|
|
CORS_ORIGINS=https://yourdomain.com
|
|
ENABLE_DOCS=false
|
|
DEBUG=false
|
|
LOG_LEVEL=warn
|
|
JWT_SECRET=strong-production-secret
|
|
```
|
|
|
|
### Available Variables
|
|
|
|
| Variable | Description | Default |
|
|
| -------------- | ---------------------------- | ----------------------- |
|
|
| `NODE_ENV` | Environment mode | `development` |
|
|
| `PORT` | Application port | `3000` |
|
|
| `DATABASE_URL` | PostgreSQL connection string | Required |
|
|
| `CORS_ORIGINS` | Allowed CORS origins | `http://localhost:3000` |
|
|
| `ENABLE_DOCS` | Enable Swagger documentation | `true` |
|
|
| `LOG_LEVEL` | Logging level | `info` |
|
|
| `JWT_SECRET` | JWT signing secret | Required for auth |
|
|
|
|
## 🧪 Testing
|
|
|
|
### API Testing
|
|
|
|
Use the included `icd.http` file with VS Code REST Client extension:
|
|
|
|
```http
|
|
### Import ICD Data
|
|
POST http://localhost:3000/icd/import
|
|
|
|
### Search ICD Codes
|
|
GET http://localhost:3000/icd/search?search=diabetes&page=1&limit=10
|
|
|
|
### Get Statistics
|
|
GET http://localhost:3000/icd/statistics
|
|
```
|
|
|
|
### Unit Tests
|
|
|
|
```bash
|
|
# Run tests
|
|
npm run test
|
|
|
|
# Watch mode
|
|
npm run test:watch
|
|
|
|
# Coverage
|
|
npm run test:cov
|
|
|
|
# E2E tests
|
|
npm run test:e2e
|
|
```
|
|
|
|
## 🔧 Development
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
src/
|
|
├── main.ts # Application entry point
|
|
├── app.module.ts # Root module
|
|
├── icd/ # ICD module
|
|
│ ├── icd.controller.ts # REST endpoints
|
|
│ ├── icd.service.ts # Business logic
|
|
│ ├── icd.module.ts # Module definition
|
|
│ └── dto/ # Data transfer objects
|
|
├── health/ # Health check module
|
|
└── prisma/ # Database schema
|
|
```
|
|
|
|
### Scripts
|
|
|
|
```bash
|
|
# Development
|
|
npm run start:dev # Start with hot reload
|
|
npm run start:debug # Start with debugger
|
|
|
|
# Build
|
|
npm run build # Build for production
|
|
npm run start:prod # Start production build
|
|
|
|
# Database
|
|
npx prisma studio # Open Prisma Studio
|
|
npx prisma db push # Push schema changes (dev only)
|
|
npx prisma generate # Generate Prisma client
|
|
|
|
# Code Quality
|
|
npm run lint # Run ESLint
|
|
npm run format # Format with Prettier
|
|
```
|
|
|
|
### Adding New Features
|
|
|
|
1. **Create DTOs** with validation decorators
|
|
2. **Add Swagger decorators** for API documentation
|
|
3. **Write unit tests** for services and controllers
|
|
4. **Update database schema** if needed
|
|
5. **Create migration** with descriptive name
|
|
|
|
## 📦 Deployment
|
|
|
|
### Docker Production
|
|
|
|
```dockerfile
|
|
# Build stage
|
|
FROM node:18-alpine AS builder
|
|
WORKDIR /app
|
|
COPY package*.json ./
|
|
RUN npm ci --only=production
|
|
COPY . .
|
|
RUN npm run build
|
|
|
|
# Production stage
|
|
FROM node:18-alpine AS production
|
|
WORKDIR /app
|
|
COPY --from=builder /app/dist ./dist
|
|
COPY --from=builder /app/node_modules ./node_modules
|
|
COPY package*.json ./
|
|
EXPOSE 3000
|
|
CMD ["node", "dist/main"]
|
|
```
|
|
|
|
### Environment Setup
|
|
|
|
1. **Production Database**: Use managed PostgreSQL (AWS RDS, Google Cloud SQL)
|
|
2. **Environment Variables**: Set secure values for production
|
|
3. **SSL/TLS**: Enable HTTPS in production
|
|
4. **Monitoring**: Add application monitoring (Prometheus, Grafana)
|
|
5. **Logging**: Configure centralized logging
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
**Port 5432 already in use:**
|
|
|
|
```bash
|
|
# Check what's using the port
|
|
netstat -ano | findstr :5432
|
|
# Stop local PostgreSQL service
|
|
```
|
|
|
|
**Database connection failed:**
|
|
|
|
```bash
|
|
# Check if container is running
|
|
docker-compose ps
|
|
# Check logs
|
|
docker-compose logs
|
|
# Restart database
|
|
docker-compose restart
|
|
```
|
|
|
|
**Prisma can't connect:**
|
|
|
|
```bash
|
|
# Verify DATABASE_URL in .env
|
|
# Test connection
|
|
npx prisma db pull
|
|
```
|
|
|
|
**Build errors:**
|
|
|
|
```bash
|
|
# Clean install
|
|
rm -rf node_modules package-lock.json
|
|
npm install
|
|
```
|
|
|
|
## 📄 License
|
|
|
|
This project is licensed under the MIT License.
|
|
|
|
## 🤝 Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Add tests
|
|
5. Submit a pull request
|
|
|
|
## 📞 Support
|
|
|
|
For questions and support:
|
|
|
|
- Check the [API documentation](http://localhost:3000/docs)
|
|
- Review the troubleshooting section
|
|
- Create an issue in the repository
|
|
|
|
---
|
|
|
|
**Ready to manage ICD codes efficiently!** 🚀
|