90ccb8b4ec
Major Updates: - Implement Meilisearch-inspired design system (purple/pink gradients) - Complete frontend polish for all views (Home, Search, Document, Jobs) - Add PDF.js document viewer with full page navigation - Create real-time Jobs dashboard with auto-refresh - Fix Meilisearch authentication (generated secure master key) - Configure Vite for WSL2 → Windows browser access (host: 0.0.0.0) Frontend Components: - HomeView: Hero section, gradient search bar, feature cards, footer - SearchView: Real-time search, highlighted matches, result cards - DocumentView: PDF.js viewer, dark theme, page controls - JobsView: NEW - Real-time job tracking, progress bars, status badges Design System: - Colors: Purple (#d946ef) & Pink (#f43f5e) gradients - Typography: Inter font family (300-900 weights) - Components: Gradient buttons, backdrop blur, smooth animations - Responsive: Mobile-friendly layouts with Tailwind CSS Infrastructure: - Service management scripts (start-all.sh, stop-all.sh) - Comprehensive documentation in docs/handover/ - Frontend quickstart guide for WSL2 users - Master roadmap with verticals & horizontals strategy Documentation: - Complete handover documentation - Frontend polish summary with all changes - Branding creative brief for designers - Yacht management features roadmap - Platform strategy (4 verticals, 17 horizontals) Build Status: - Clean build with no errors - Bundle size: 150KB gzipped - Dev server on port 8080 (accessible from Windows) - Production ready 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
248 lines
6.5 KiB
Markdown
248 lines
6.5 KiB
Markdown
# NaviDocs Port Allocation Strategy
|
|
|
|
**Date:** 2025-10-19
|
|
**Purpose:** Avoid port conflicts with other projects (FastFile, frank-ai, etc.)
|
|
**Constraint:** **DO NOT use ports 3000-5500** (reserved for other projects)
|
|
|
|
---
|
|
|
|
## Port Allocation
|
|
|
|
### NaviDocs Ports (NEW)
|
|
|
|
| Service | Old Port | New Port | Reason |
|
|
|---------|----------|----------|--------|
|
|
| **Backend API** | 3001 | **8001** | Outside 3000-5500 range, common for APIs |
|
|
| **Frontend Dev** | 5173 | **8080** | Outside 3000-5500 range, standard web port |
|
|
|
|
### External Services (UNCHANGED)
|
|
|
|
| Service | Port | Status | Notes |
|
|
|---------|------|--------|-------|
|
|
| **Meilisearch** | 7700 | ✅ Keep | Already outside restricted range |
|
|
| **Redis** | 6379 | ✅ Keep | Already outside restricted range |
|
|
| **Gitea** | 4000 | ✅ Keep | Explicitly requested to keep |
|
|
|
|
### StackCP Test Ports
|
|
|
|
| Service | Old Port | New Port | Reason |
|
|
|---------|----------|----------|--------|
|
|
| **Test Server** | 3333 | **8333** | Outside 3000-5500 range |
|
|
|
|
---
|
|
|
|
## Port Range Strategy
|
|
|
|
### Avoided Ranges
|
|
- **3000-5500**: Reserved for other projects (FastFile, frank-ai, etc.)
|
|
|
|
### Safe Ranges for NaviDocs
|
|
- **8000-8999**: Web services and APIs (chosen for NaviDocs)
|
|
- **9000-9999**: Alternative if 8000s conflict
|
|
- **6000-6999**: Database and cache services (Redis already uses 6379)
|
|
- **7000-7999**: Search and indexing services (Meilisearch already uses 7700)
|
|
|
|
---
|
|
|
|
## Changes Required
|
|
|
|
### Configuration Files
|
|
|
|
1. **`server/.env`**
|
|
- `PORT=3001` → `PORT=8001`
|
|
|
|
2. **`client/vite.config.js`**
|
|
- `port: 5173` → `port: 8080`
|
|
- `target: 'http://localhost:3001'` → `target: 'http://localhost:8001'`
|
|
|
|
### Documentation Files (24 files)
|
|
|
|
Files containing port references that need updating:
|
|
|
|
**Root Documentation:**
|
|
1. `README.md` - Frontend port 5173 → 8080
|
|
2. `QUICKSTART.md` - Backend port references
|
|
3. `TEST_RESULTS.md` - Backend 3001 → 8001
|
|
4. `BUILD_COMPLETE.md` - Frontend 5173 → 8080
|
|
5. `SERVICES_STATUS.md` - Both ports
|
|
6. `SESSION_STATUS.md` - Both ports
|
|
7. `NAVIDOCS_HANDOVER.md` - Both ports
|
|
8. `IMPLEMENTATION_COMPLETE.md` - Backend 3001 → 8001
|
|
9. `GOOGLE_DRIVE_OCR_QUICKSTART.md` - Backend 3001 → 8001
|
|
10. `OCR_PIPELINE_SETUP.md` - Redis port (keep 6379)
|
|
|
|
**StackCP Documentation:**
|
|
11. `STACKCP_EVALUATION_REPORT.md` - Backend 3001 → 8001, test 3333 → 8333
|
|
12. `STACKCP_VERIFICATION_SUMMARY.md` - Test 3333 → 8333
|
|
13. `STACKCP_ARCHITECTURE_ANALYSIS.md` - Backend 3001 → 8001
|
|
14. `docs/DEPLOYMENT_STACKCP.md` - Backend 3001 → 8001
|
|
15. `docs/STACKCP_QUICKSTART.md` - Backend 3001 → 8001
|
|
|
|
**Server Documentation:**
|
|
16. `server/API_SUMMARY.md` - Backend 3001 → 8001
|
|
17. `server/routes/README.md` - Backend 3001 → 8001
|
|
18. `server/services/README.md` - Redis port (keep 6379)
|
|
19. `server/workers/README.md` - Redis port (keep 6379)
|
|
|
|
**Config Examples:**
|
|
20. `server/.env.example` - Backend 3001 → 8001
|
|
|
|
---
|
|
|
|
## URL Changes Summary
|
|
|
|
### Development URLs
|
|
|
|
**OLD:**
|
|
- Backend API: `http://localhost:3001`
|
|
- Frontend: `http://localhost:5173` or `http://localhost:5174`
|
|
- Health Check: `http://localhost:3001/health`
|
|
|
|
**NEW:**
|
|
- Backend API: `http://localhost:8001`
|
|
- Frontend: `http://localhost:8080`
|
|
- Health Check: `http://localhost:8001/health`
|
|
|
|
### Production/StackCP URLs
|
|
|
|
**OLD:**
|
|
- Backend: `http://127.0.0.1:3001`
|
|
|
|
**NEW:**
|
|
- Backend: `http://127.0.0.1:8001`
|
|
|
|
---
|
|
|
|
## Verification Checklist
|
|
|
|
After applying changes, verify:
|
|
|
|
- [ ] Server starts on port 8001: `cd server && node index.js`
|
|
- [ ] Frontend starts on port 8080: `cd client && npm run dev`
|
|
- [ ] Vite proxy works: Visit `http://localhost:8080` and test API calls
|
|
- [ ] No port conflicts: `sudo lsof -i :8001` and `sudo lsof -i :8080` show only NaviDocs
|
|
- [ ] Health check works: `curl http://localhost:8001/health`
|
|
- [ ] Upload works: `curl -X POST http://localhost:8001/api/upload -F "file=@test.pdf"`
|
|
|
|
---
|
|
|
|
## Migration Notes
|
|
|
|
### For Developers
|
|
|
|
1. **Update environment variables:**
|
|
```bash
|
|
cd /home/setup/navidocs/server
|
|
# Edit .env file
|
|
# Change PORT=3001 to PORT=8001
|
|
```
|
|
|
|
2. **No code changes needed** - ports are configured via environment variables
|
|
|
|
3. **Restart services:**
|
|
```bash
|
|
# Stop old services if running
|
|
pkill -f "node.*index.js"
|
|
pkill -f "vite"
|
|
|
|
# Start with new ports
|
|
cd /home/setup/navidocs/server
|
|
node index.js # Will use port 8001
|
|
|
|
cd /home/setup/navidocs/client
|
|
npm run dev # Will use port 8080
|
|
```
|
|
|
|
### For Documentation Updates
|
|
|
|
Use find-and-replace:
|
|
- `localhost:3001` → `localhost:8001`
|
|
- `127.0.0.1:3001` → `127.0.0.1:8001`
|
|
- `localhost:5173` → `localhost:8080`
|
|
- `localhost:5174` → `localhost:8080`
|
|
- `:3333` → `:8333` (StackCP test server)
|
|
|
|
**DO NOT replace:**
|
|
- `:6379` (Redis)
|
|
- `:7700` (Meilisearch)
|
|
- `:4000` (Gitea)
|
|
|
|
---
|
|
|
|
## Rationale
|
|
|
|
### Why 8001 for Backend?
|
|
|
|
- **Outside restricted range** (3000-5500)
|
|
- **Common for APIs** (8000-8999 range)
|
|
- **Memorable** (8001 = "eight thousand one")
|
|
- **No conflicts** with standard services
|
|
|
|
### Why 8080 for Frontend?
|
|
|
|
- **Outside restricted range** (3000-5500)
|
|
- **Standard alternative HTTP port** (commonly used for web apps)
|
|
- **Well-known** (8080 is universally recognized)
|
|
- **No conflicts** with common services
|
|
|
|
---
|
|
|
|
## Future Port Assignments
|
|
|
|
If NaviDocs needs additional services:
|
|
|
|
| Service | Suggested Port | Range |
|
|
|---------|----------------|-------|
|
|
| **Monitoring** | 9001 | 9000-9999 |
|
|
| **Metrics** | 9002 | 9000-9999 |
|
|
| **Admin Panel** | 8888 | 8000-8999 |
|
|
| **WebSocket** | 8081 | 8000-8999 |
|
|
|
|
---
|
|
|
|
## Related Projects
|
|
|
|
### Port Allocations (Assumed)
|
|
|
|
| Project | Port Range | Status |
|
|
|---------|-----------|--------|
|
|
| **FastFile** | 3000-5500 | Active (avoid) |
|
|
| **frank-ai/lilian1** | 3000-5500 | Legacy (should be stopped) |
|
|
| **NaviDocs** | 8000-8999 | Active (this project) |
|
|
| **System Services** | Various | Keep (Gitea 4000, Redis 6379, Meilisearch 7700) |
|
|
|
|
---
|
|
|
|
## Emergency Rollback
|
|
|
|
If the new ports cause issues:
|
|
|
|
1. **Revert `.env`:**
|
|
```bash
|
|
cd /home/setup/navidocs/server
|
|
# Change PORT=8001 back to PORT=3001
|
|
```
|
|
|
|
2. **Revert `vite.config.js`:**
|
|
```bash
|
|
cd /home/setup/navidocs/client
|
|
# Change port: 8080 back to port: 5173
|
|
# Change target: 'http://localhost:8001' back to 'http://localhost:3001'
|
|
```
|
|
|
|
3. **Restart services**
|
|
|
|
4. **File an issue** documenting the conflict
|
|
|
|
---
|
|
|
|
**Status:** Ready for implementation
|
|
**Impact:** Low (environment variable changes only)
|
|
**Risk:** Minimal (easy rollback)
|
|
**Timeline:** 15-30 minutes for full migration
|
|
|
|
---
|
|
|
|
**Document Version:** 1.0
|
|
**Last Updated:** 2025-10-19
|
|
**Author:** Claude Code
|