Update README.md
This commit is contained in:
parent
ff18def8ba
commit
df2b816f79
258
README.md
258
README.md
@ -1,135 +1,153 @@
|
|||||||
# Knowledge Article System - Project Roadmap
|
# Knowledge Article System
|
||||||
|
|
||||||
## Project Overview
|
A simple desktop application for IT teams to document and search process knowledge, troubleshooting steps, and technical information.
|
||||||
A minimal, local desktop knowledge management system for a small IT team (3 users) to document and search process knowledge.
|
|
||||||
|
|
||||||
**Tech Stack:**
|
## Quick Start
|
||||||
- Backend: Node.js + SQLite
|
|
||||||
- Frontend: React + JavaScript
|
|
||||||
- Key Features: Basic CRUD, simple search, rich text editing
|
|
||||||
- **Scope:** Single developer, 1-week MVP, then iterate based on real usage
|
|
||||||
|
|
||||||
---
|
### For End Users
|
||||||
|
See [USER_GUIDE.md](USER_GUIDE.md) for complete usage instructions.
|
||||||
|
|
||||||
## Week 1: MVP Sprint (Days 1-5)
|
**TL;DR:**
|
||||||
|
1. Start backend: `cd server && node server.js`
|
||||||
|
2. Start frontend: `cd client/kb-frontend && npm run dev`
|
||||||
|
3. Open browser to `http://localhost:5173`
|
||||||
|
|
||||||
### Goal
|
### For Developers
|
||||||
Get a working, usable system in the hands of the team by end of week
|
See [TECHNICAL_DOCUMENTATION.md](TECHNICAL_DOCUMENTATION.md) for architecture, API docs, and maintenance info.
|
||||||
|
|
||||||
### Day 1-2: Backend Basics
|
## Features
|
||||||
- [ ] Initialize Node.js project
|
|
||||||
- [ ] Set up Express server
|
|
||||||
- [ ] Create SQLite database with single `articles` table
|
|
||||||
- id (primary key, auto-increment)
|
|
||||||
- ka_number (unique, e.g., "KA001")
|
|
||||||
- title (text)
|
|
||||||
- content (text, will store HTML)
|
|
||||||
- created_at (timestamp)
|
|
||||||
- updated_at (timestamp)
|
|
||||||
- [ ] Implement basic API endpoints:
|
|
||||||
- `GET /api/articles` - Get all articles
|
|
||||||
- `GET /api/articles/:id` - Get one article
|
|
||||||
- `POST /api/articles` - Create article
|
|
||||||
- `PUT /api/articles/:id` - Update article
|
|
||||||
- `DELETE /api/articles/:id` - Delete article
|
|
||||||
- `GET /api/search?q=query` - Basic text search
|
|
||||||
- [ ] Test endpoints with Postman or Thunder Client
|
|
||||||
|
|
||||||
### Day 3-4: Frontend Basics
|
✅ **Create** knowledge articles with auto-generated KA numbers
|
||||||
- [ ] Initialize React app (Vite for faster setup)
|
✅ **Search** by title, content, or KA number
|
||||||
- [ ] Create basic layout:
|
✅ **Edit** existing articles
|
||||||
- Search bar at top
|
✅ **Delete** articles with confirmation
|
||||||
- Article list/results view
|
✅ **Simple interface** - no authentication needed for local use
|
||||||
- Article detail/edit view
|
|
||||||
- [ ] Integrate a simple rich text editor (recommend: React Quill - easiest to set up)
|
|
||||||
- [ ] Connect to backend API
|
|
||||||
- [ ] Implement basic routing (list view ↔ detail view)
|
|
||||||
|
|
||||||
### Day 5: Integration & Testing
|
## System Requirements
|
||||||
- [ ] Wire up search functionality
|
|
||||||
- [ ] Test create/edit/delete workflows
|
|
||||||
- [ ] Add basic styling (make it readable, doesn't need to be pretty)
|
|
||||||
- [ ] Fix critical bugs
|
|
||||||
- [ ] Write quick README with startup instructions
|
|
||||||
- [ ] Get team to test it
|
|
||||||
|
|
||||||
### MVP Feature Set (Absolute Minimum)
|
- Node.js (v16+)
|
||||||
✅ Create new KA with title and rich text content
|
- Modern web browser
|
||||||
✅ View list of all KAs
|
- Ports 9000 and 5173 available
|
||||||
✅ Click to view/edit a specific KA
|
|
||||||
✅ Basic search (title + content)
|
|
||||||
✅ Delete KA (with confirmation)
|
|
||||||
✅ Auto-generate KA numbers
|
|
||||||
|
|
||||||
### Explicitly OUT of Scope for Week 1
|
## Project Structure
|
||||||
❌ Categories/tags
|
|
||||||
❌ Version history
|
|
||||||
❌ Advanced search features
|
|
||||||
❌ File attachments
|
|
||||||
❌ Fancy UI/styling
|
|
||||||
❌ Keyboard shortcuts
|
|
||||||
❌ Statistics/analytics
|
|
||||||
❌ Export features
|
|
||||||
|
|
||||||
---
|
```
|
||||||
|
knowledge_article_system/
|
||||||
## Week 2+: Post-MVP Iteration
|
├── server/ # Backend (Node.js + Express + SQLite)
|
||||||
|
│ ├── server.js # API server
|
||||||
### Approach
|
│ ├── db.js # Database functions
|
||||||
Now that the team is using it, add features based on actual needs
|
│ └── package.json
|
||||||
|
│
|
||||||
### Potential Additions (Priority Order)
|
├── client/ # Frontend (React + Vite)
|
||||||
1. **Categories/Tags** - If team needs better organization
|
│ └── kb-frontend/
|
||||||
2. **Search improvements** - Fuzzy search, search by KA number only
|
│ ├── src/
|
||||||
3. **Better styling** - Make it look nicer once functionality is solid
|
│ │ ├── App.jsx
|
||||||
4. **Recent articles list** - Quick access to commonly used KAs
|
│ │ └── components/
|
||||||
5. **Edit history** - Track who changed what and when
|
│ └── package.json
|
||||||
6. **Attachments** - Add screenshots or log files
|
│
|
||||||
7. **Templates** - Pre-filled formats for common issue types
|
├── USER_GUIDE.md # End user documentation
|
||||||
8. **Export to PDF** - For printing or sharing outside the tool
|
└── TECHNICAL_DOCUMENTATION.md # Developer documentation
|
||||||
9. **Backup/restore** - Easy database backup
|
|
||||||
|
|
||||||
### Iteration Strategy
|
|
||||||
- Get feedback from users after first week
|
|
||||||
- Pick ONE feature to add based on biggest pain point
|
|
||||||
- Implement, test, repeat
|
|
||||||
- Don't add features "just because" - only add what is actually needed
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Success Criteria for Week 1
|
|
||||||
|
|
||||||
- [ ] You can create a KA in under 30 seconds
|
|
||||||
- [ ] You can search and find a KA in under 10 seconds
|
|
||||||
- [ ] You can edit an existing KA
|
|
||||||
- [ ] All 3 team members can run it on their machines
|
|
||||||
- [ ] No critical bugs that prevent basic use
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Database Schema (Minimal)
|
|
||||||
|
|
||||||
```sql
|
|
||||||
CREATE TABLE articles (
|
|
||||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
||||||
ka_number TEXT UNIQUE NOT NULL,
|
|
||||||
title TEXT NOT NULL,
|
|
||||||
content TEXT,
|
|
||||||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
|
||||||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
|
||||||
);
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Tech Stack
|
||||||
|
|
||||||
|
**Backend:**
|
||||||
|
- Node.js + Express
|
||||||
|
- SQLite (sql.js)
|
||||||
|
- CORS enabled
|
||||||
|
|
||||||
|
**Frontend:**
|
||||||
|
- React 19
|
||||||
|
- Vite
|
||||||
|
- Vanilla CSS
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Backend
|
||||||
|
cd server
|
||||||
|
npm install
|
||||||
|
|
||||||
|
# Frontend
|
||||||
|
cd client/kb-frontend
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
## Running
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Terminal 1 - Backend
|
||||||
|
cd server
|
||||||
|
node server.js
|
||||||
|
|
||||||
|
# Terminal 2 - Frontend
|
||||||
|
cd client/kb-frontend
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
Access at: `http://localhost:5173`
|
||||||
|
|
||||||
|
## API Endpoints
|
||||||
|
|
||||||
|
| Method | Endpoint | Description |
|
||||||
|
|--------|----------|-------------|
|
||||||
|
| GET | `/api/articles` | Get all articles |
|
||||||
|
| GET | `/api/articles/:ka_number` | Get specific article |
|
||||||
|
| POST | `/api/articles` | Create new article |
|
||||||
|
| PUT | `/api/articles/:ka_number` | Update article |
|
||||||
|
| DELETE | `/api/articles/:ka_number` | Delete article |
|
||||||
|
| GET | `/api/search?q=query` | Search articles |
|
||||||
|
|
||||||
|
## Database
|
||||||
|
|
||||||
|
- **Type:** SQLite (file-based)
|
||||||
|
- **Location:** `server/ka.db`
|
||||||
|
- **Backup:** Copy `ka.db` file regularly
|
||||||
|
|
||||||
|
## MVP Status (Week 1) ✅
|
||||||
|
|
||||||
|
All core features complete:
|
||||||
|
- [x] Backend API with full CRUD operations
|
||||||
|
- [x] Frontend with search and article management
|
||||||
|
- [x] Auto-generated KA numbers (KA001, KA002, etc.)
|
||||||
|
- [x] Create, view, edit, delete workflows
|
||||||
|
- [x] Search functionality
|
||||||
|
- [x] Basic styling and responsive layout
|
||||||
|
|
||||||
|
## Future Enhancements
|
||||||
|
|
||||||
|
Potential additions based on team feedback:
|
||||||
|
- Entra OAuth
|
||||||
|
- Freshdesk Integration
|
||||||
|
- Improved Rich text editor
|
||||||
|
- Fuzzy search
|
||||||
|
- Script-based deployment
|
||||||
|
- Docker container
|
||||||
|
- Article categories/tags
|
||||||
|
- File attachments (screenshots, logs)
|
||||||
|
- Version history
|
||||||
|
- Export to PDF
|
||||||
|
- Article templates
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
This is an internal tool. Enhancements will be added based on real usage and feedback.
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT License
|
||||||
|
|
||||||
|
## Author
|
||||||
|
|
||||||
|
Matt Taylor
|
||||||
|
|
||||||
|
## Support
|
||||||
|
|
||||||
|
- Check [USER_GUIDE.md](USER_GUIDE.md) for usage help
|
||||||
|
- Check [TECHNICAL_DOCUMENTATION.md](TECHNICAL_DOCUMENTATION.md) for technical details
|
||||||
|
- Contact Matt for bugs or feature requests
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Risk Management
|
**Version:** 0.0.1 (MVP)
|
||||||
|
**Status:** ✅ Production Ready for Internal Use
|
||||||
### Main Risks
|
|
||||||
1. **Scope creep in week 1** - focus only on core features
|
|
||||||
2. **Time sink on editor** - Use React Quill, don't build custom
|
|
||||||
3. **Database issues** - Keep schema simple, optimize later
|
|
||||||
|
|
||||||
### Mitigation
|
|
||||||
- Set a timer for each task, move on if taking too long
|
|
||||||
- Use libraries, don't reinvent the wheel
|
|
||||||
- Manual testing only for week 1
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user