From df2b816f795ab6d47ead90d1cf486ef50bd0c5ee Mon Sep 17 00:00:00 2001 From: TheLeo Date: Tue, 25 Nov 2025 22:38:00 +0000 Subject: [PATCH] Update README.md --- README.md | 258 +++++++++++++++++++++++++++++------------------------- 1 file changed, 138 insertions(+), 120 deletions(-) diff --git a/README.md b/README.md index 41cf9f5..2e1a992 100644 --- a/README.md +++ b/README.md @@ -1,135 +1,153 @@ -# Knowledge Article System - Project Roadmap +# Knowledge Article System -## Project Overview -A minimal, local desktop knowledge management system for a small IT team (3 users) to document and search process knowledge. +A simple desktop application for IT teams to document and search process knowledge, troubleshooting steps, and technical information. -**Tech Stack:** -- 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 +## Quick Start ---- +### 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 -Get a working, usable system in the hands of the team by end of week +### For Developers +See [TECHNICAL_DOCUMENTATION.md](TECHNICAL_DOCUMENTATION.md) for architecture, API docs, and maintenance info. -### Day 1-2: Backend Basics -- [ ] 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 +## Features -### Day 3-4: Frontend Basics -- [ ] Initialize React app (Vite for faster setup) -- [ ] Create basic layout: - - Search bar at top - - Article list/results view - - 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) +✅ **Create** knowledge articles with auto-generated KA numbers +✅ **Search** by title, content, or KA number +✅ **Edit** existing articles +✅ **Delete** articles with confirmation +✅ **Simple interface** - no authentication needed for local use -### Day 5: Integration & Testing -- [ ] 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 +## System Requirements -### MVP Feature Set (Absolute Minimum) -✅ Create new KA with title and rich text content -✅ View list of all KAs -✅ Click to view/edit a specific KA -✅ Basic search (title + content) -✅ Delete KA (with confirmation) -✅ Auto-generate KA numbers +- Node.js (v16+) +- Modern web browser +- Ports 9000 and 5173 available -### Explicitly OUT of Scope for Week 1 -❌ Categories/tags -❌ Version history -❌ Advanced search features -❌ File attachments -❌ Fancy UI/styling -❌ Keyboard shortcuts -❌ Statistics/analytics -❌ Export features +## Project Structure ---- - -## Week 2+: Post-MVP Iteration - -### Approach -Now that the team is using it, add features based on actual needs - -### Potential Additions (Priority Order) -1. **Categories/Tags** - If team needs better organization -2. **Search improvements** - Fuzzy search, search by KA number only -3. **Better styling** - Make it look nicer once functionality is solid -4. **Recent articles list** - Quick access to commonly used KAs -5. **Edit history** - Track who changed what and when -6. **Attachments** - Add screenshots or log files -7. **Templates** - Pre-filled formats for common issue types -8. **Export to PDF** - For printing or sharing outside the tool -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 -); +``` +knowledge_article_system/ +├── server/ # Backend (Node.js + Express + SQLite) +│ ├── server.js # API server +│ ├── db.js # Database functions +│ └── package.json +│ +├── client/ # Frontend (React + Vite) +│ └── kb-frontend/ +│ ├── src/ +│ │ ├── App.jsx +│ │ └── components/ +│ └── package.json +│ +├── USER_GUIDE.md # End user documentation +└── TECHNICAL_DOCUMENTATION.md # Developer documentation ``` +## 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 - -### 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 +**Version:** 0.0.1 (MVP) +**Status:** ✅ Production Ready for Internal Use