knowledge_article_system/README.md

# Knowledge Article System - Project Roadmap

## Project Overview
A minimal, local desktop knowledge management system for a small IT team (3 users) to document and search process knowledge.

**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

---

## Week 1: MVP Sprint (Days 1-5)

### Goal
Get a working, usable system in the hands of the team by end of week

### 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

### 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)

### 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

### 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

### 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

---

## 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 the 3 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 team actually needs

---

## Quick Start Guide (Day 1 Setup)

### Backend Setup
```bash
mkdir ka-system-backend
cd ka-system-backend
npm init -y
npm install express better-sqlite3 cors
```

Create minimal file structure:
- `server.js` - Express server
- `db.js` - Database setup and queries
- `database.db` - SQLite database (created automatically)

### Frontend Setup
```bash
npm create vite@latest ka-system-frontend -- --template react
cd ka-system-frontend
npm install
npm install axios react-quill
```

### Running the System
1. Terminal 1: `node server.js` (backend on port 3001)
2. Terminal 2: `npm run dev` (frontend on port 5173)
3. Open browser to `localhost:5173`

---

## 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

If these work, you have a successful MVP. Everything else is polish.

---

## 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
);
```

Add indexes after MVP if search is slow:
```sql
CREATE INDEX idx_title ON articles(title);
CREATE INDEX idx_content ON articles(content);
```

---

## Risk Management

### Main Risks
1. **Scope creep in week 1** - Stay disciplined, MVP only
2. **Time sink on editor** - Use React Quill, don't build custom
3. **Database issues** - Keep schema simple, optimize later
4. **Team won't use it** - Get feedback early and often

### 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
- Share progress daily with team