added documentation

2025-11-25 16:41:54 -06:00 · 2025-11-25 16:41:54 -06:00 · 0f9da0b1a7
commit 0f9da0b1a7
parent df2b816f79
2 changed files with 721 additions and 0 deletions
--- a/TECHNICAL_DOCUMENTATION.md
+++ b/TECHNICAL_DOCUMENTATION.md
@ -0,0 +1,486 @@
+ Knowledge Article System - Technical Documentation
+
+## System Architecture
+
+### Overview
+The KA System is a local desktop application with a client-server architecture:
+- **Backend:** Node.js + Express + SQLite (sql.js)
+- **Frontend:** React (Vite)
+- **Database:** SQLite file-based database
+
+### Components
+
+```
+knowledge_article_system/
+├── server/                 # Backend
+│   ├── server.js          # Express server
+│   ├── db.js              # Database functions
+│   ├── ka.db              # SQLite database (created at runtime)
+│   └── package.json       # Dependencies
+│
+└── client/                # Frontend
+    ├── src/
+    │   ├── App.jsx        # Main application component
+    │   ├── components/    # UI components
+    │   └── App.css        # Styles
+    └── package.json       # Dependencies
+```
+
+---
+
+## Installation & Setup
+
+### Prerequisites
+- Node.js (v16 or higher)
+- npm (comes with Node.js)
+
+### First-Time Setup
+
+#### Backend Setup
+```bash
+cd server
+npm install
+```
+
+Dependencies installed:
+- `express` - Web server framework
+- `sql.js` - SQLite database
+- `cors` - Cross-origin resource sharing
+
+#### Frontend Setup
+```bash
+cd client/kb-frontend
+npm install
+```
+
+Dependencies installed:
+- `react` - UI framework
+- `vite` - Build tool and dev server
+- `react-quill` - Rich text editor (optional, currently using textarea)
+
+### Running the Application
+
+#### Start Backend (Terminal 1)
+```bash
+cd server
+node server.js
+```
+Server runs on: `http://localhost:9000`
+
+#### Start Frontend (Terminal 2)
+```bash
+cd client/kb-frontend
+npm run dev
+```
+Frontend runs on: `http://localhost:5173`
+
+---
+
+## API Documentation
+
+### Base URL
+```
+http://localhost:9000/api
+```
+
+### Endpoints
+
+#### Get All Articles
+```
+GET /api/articles
+```
+Returns: Array of all articles, ordered by creation date (newest first)
+
+**Response:**
+```json
+[
+  {
+    "id": 1,
+    "ka_number": "KA001",
+    "title": "How to Reset Password",
+    "content": "Steps to reset...",
+    "created_at": "2024-11-24 12:00:00",
+    "updated_at": null
+  }
+]
+```
+
+#### Get Single Article
+```
+GET /api/articles/:ka_number
+```
+Parameters: `ka_number` (e.g., "KA001")
+
+Returns: Single article object or 404 if not found
+
+#### Search Articles
+```
+GET /api/search?q={query}
+```
+Query Parameters: `q` - search term
+
+Searches across: title, content, and ka_number
+
+Returns: Array of matching articles
+
+#### Create Article
+```
+POST /api/articles
+```
+Headers: `Content-Type: application/json`
+
+Body:
+```json
+{
+  "title": "Article Title",
+  "content": "Article content..."
+}
+```
+
+Returns: Newly created article with auto-generated KA number
+
+#### Update Article
+```
+PUT /api/articles/:ka_number
+```
+Headers: `Content-Type: application/json`
+
+Body:
+```json
+{
+  "title": "Updated Title",
+  "content": "Updated content..."
+}
+```
+
+Returns: Updated article object
+
+#### Delete Article
+```
+DELETE /api/articles/:ka_number
+```
+Returns: Success message
+
+---
+
+## Database Schema
+
+### Articles Table
+```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
+);
+
+CREATE INDEX idx_ka_number ON articles(ka_number);
+```
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | INTEGER | Auto-incrementing primary key |
+| ka_number | TEXT | Unique identifier (KA001, KA002, etc.) |
+| title | TEXT | Article title (required) |
+| content | TEXT | Article content (HTML/text) |
+| created_at | DATETIME | Timestamp of creation |
+| updated_at | DATETIME | Timestamp of last update |
+
+### KA Number Generation
+
+KA numbers are auto-generated sequentially:
+- Format: `KA` + 3-digit number padded with zeros
+- Examples: KA001, KA002, ..., KA999
+- Logic in `db.js` → `getNextKANumber()`
+
+---
+
+## Code Structure
+
+### Backend (server.js)
+
+**Key Components:**
+- Express server initialization
+- CORS configuration for frontend access
+- JSON body parsing middleware
+- API route handlers
+- Error handling
+
+**Important:**
+- `app.use(express.json())` must be present for POST/PUT requests
+- `app.use(cors())` allows frontend to make requests
+- Database is initialized before routes are registered
+
+### Database Layer (db.js)
+
+**Functions:**
+- `initDb()` - Initialize/load database
+- `getAllArticles()` - Fetch all articles
+- `getArticle(ka_number)` - Get single article
+- `createArticle(title, content)` - Create new article
+- `updateArticle(ka_number, title, content)` - Update article
+- `deleteArticle(ka_number)` - Delete article
+- `searchArticles(query)` - Search articles
+
+**Key Points:**
+- Uses prepared statements for security
+- Database saved to disk after each write operation
+- KA numbers generated automatically
+
+### Frontend (App.jsx)
+
+**State Management:**
+- `currentView` - Controls which view to show ('list', 'detail', 'edit')
+- `selectedArticle` - Currently selected article
+- `articles` - Array of articles for the list view
+
+**Key Functions:**
+- `handleSearch()` - Search or load all articles
+- `handleArticleClick()` - View article details
+- `handleEdit()` - Switch to edit mode
+- `handleSave()` - Save new or updated article
+- `handleDelete()` - Delete article
+- `handleCreateNew()` - Create new article
+
+**Component Tree:**
+```
+App
+├── Header
+├── SearchBar (list view)
+├── ArticleList (list view)
+├── ArticleDetail (detail view)
+└── ArticleEditor (edit view)
+```
+
+---
+
+## Maintenance
+
+### Database Backup
+
+**Manual Backup:**
+```bash
+# Stop the server first
+cp server/ka.db server/ka.db.backup-$(date +%Y%m%d)
+```
+
+**Automated Backup Script (Linux/Mac):**
+```bash
+#!/bin/bash
+# save as backup-ka.sh
+
+SOURCE="./server/ka.db"
+DEST="./backups/ka.db.$(date +%Y%m%d-%H%M%S)"
+
+mkdir -p backups
+cp $SOURCE $DEST
+echo "Backup created: $DEST"
+
+# Keep only last 30 backups
+ls -t backups/ka.db.* | tail -n +31 | xargs rm -f
+```
+
+**Windows Backup Script:**
+```batch
+@echo off
+REM save as backup-ka.bat
+
+set SOURCE=server\ka.db
+set DEST=backups\ka.db.%date:~-4,4%%date:~-10,2%%date:~-7,2%
+
+if not exist backups mkdir backups
+copy %SOURCE% %DEST%
+echo Backup created: %DEST%
+```
+
+### Database Restore
+
+1. Stop the backend server
+2. Replace `server/ka.db` with backup file
+3. Restart the server
+
+### Troubleshooting
+
+**Server won't start:**
+- Check port 9000 is available
+- Verify npm dependencies installed
+- Check for syntax errors in server.js
+
+**Frontend won't connect:**
+- Verify backend is running on port 9000
+- Check CORS is enabled in server.js
+- Clear browser cache
+
+**Database corruption:**
+- Restore from backup
+- If no backup, delete ka.db and restart (creates new empty database)
+
+**Search not working:**
+- Check database has articles
+- Verify search endpoint in server.js
+- Check browser console for errors
+
+---
+
+## Deployment
+
+### Building for Production
+
+#### Backend
+Use `pkg` to create executable:
+```bash
+npm install -g pkg
+cd server
+pkg server.js
+```
+
+Creates executables:
+- `server-win.exe` (Windows)
+- `server-linux` (Linux)
+- `server-macos` (macOS)
+
+#### Frontend
+Build static files:
+```bash
+cd client/kb-frontend
+npm run build
+```
+
+Output in `dist/` folder - can be served by any static file server.
+
+### Distribution
+
+COMING SOON
+
+---
+
+## Future Enhancements
+
+Potential features for Week 2+:
+- Rich text editor improvements
+- Article categories/tags
+- Attachment support (screenshots, logs)
+- Version history
+- Export to PDF
+- Article templates
+- User tracking (who created/edited)
+- Dark mode
+- Keyboard shortcuts
+
+---
+
+## Security Considerations
+
+**Current State:**
+- No authentication (local use only)
+- No input sanitization for XSS
+- SQL injection protected by prepared statements
+
+**For Production Use:**
+- Add user authentication
+- Implement role-based access control
+- Sanitize HTML content from editor
+- Add rate limiting
+- Use HTTPS
+- Validate all inputs
+
+---
+
+## Performance
+
+**Current Performance:**
+- Handles hundreds of articles easily
+- Search is fast with ka_number index
+- No pagination needed for small teams
+
+**If Database Grows:**
+- Add pagination to article list
+- Implement full-text search (SQLite FTS5)
+- Add more indexes
+- Consider caching frequently accessed articles
+
+---
+
+## Testing
+
+### Manual Testing Checklist
+
+**Backend:**
+- [ ] Server starts without errors
+- [ ] All API endpoints return correct data
+- [ ] Create article returns new article with KA number
+- [ ] Update article modifies existing article
+- [ ] Delete article removes from database
+- [ ] Search returns relevant results
+
+**Frontend:**
+- [ ] Article list displays all articles
+- [ ] Search updates results correctly
+- [ ] Clicking article shows detail view
+- [ ] Edit button opens editor with current data
+- [ ] Save button updates article
+- [ ] Cancel button returns without saving
+- [ ] Delete button removes article after confirmation
+- [ ] Create new article generates KA number
+
+### API Testing with curl
+
+```bash
+# Create article
+curl -X POST http://localhost:9000/api/articles \
+  -H "Content-Type: application/json" \
+  -d '{"title":"Test","content":"Test content"}'
+
+# Get all articles
+curl http://localhost:9000/api/articles
+
+# Search
+curl "http://localhost:9000/api/search?q=test"
+
+# Update article
+curl -X PUT http://localhost:9000/api/articles/KA001 \
+  -H "Content-Type: application/json" \
+  -d '{"title":"Updated","content":"New content"}'
+
+# Delete article
+curl -X DELETE http://localhost:9000/api/articles/KA001
+```
+
+---
+
+## Version History
+
+### v0.0.1 (MVP) - Week 1
+**Features:**
+- Basic CRUD operations (Create, Read, Update, Delete)
+- Search functionality (title, content, KA number)
+- Auto-generated KA numbers
+- Simple text editor (textarea)
+- Responsive layout
+- Local SQLite database
+
+**Known Limitations:**
+- No rich text editing (plain text/basic HTML only)
+- No authentication
+- No version history
+- No attachments
+- No categories/tags
+
+---
+
+## Support
+
+For issues or questions:
+- Check this documentation
+- Review USER_GUIDE.md for usage questions
+- Contact: Matt Taylor (developer)
+
+---
+
+## License
+
+MIT License
--- a/USER_GUIDE.md
+++ b/USER_GUIDE.md
@ -0,0 +1,235 @@
+# Knowledge Article System - User Guide
+
+## Overview
+
+The Knowledge Article System is a simple desktop application for documenting and searching IT processes, troubleshooting steps, and other technical knowledge.
+
+---
+
+## Getting Started
+
+### Starting the Application
+
+1. **Start the backend server:**
+   - Navigate to the server folder
+   - Run the server executable or `node server.js`
+   - Server will run on port 9000
+
+2. **Start the frontend:**
+   - Navigate to the frontend folder
+   - Run `npm run dev`
+   - Open your browser to `http://localhost:5173`
+
+---
+
+## Using the System
+
+### Searching for Articles
+
+1. When you first open the application, you'll see a list of all knowledge articles
+2. Use the **search bar** at the top to find specific articles
+3. You can search by:
+   - **KA Number** (e.g., "KA001")
+   - **Article Title** (e.g., "password reset")
+   - **Article Content** (e.g., "printer")
+
+4. Search results update automatically
+5. Clear the search box to see all articles again
+
+### Viewing an Article
+
+1. Click on any article in the list to view it
+2. The article will display:
+   - KA Number (e.g., KA001)
+   - Title
+   - Creation date
+   - Full content
+3. Click the **← Back** button to return to the article list
+
+### Creating a New Article
+
+1. From the article list view, click the **+ Create New Article** button
+2. Enter the article information:
+   - **Title:** Brief description of the issue or process
+   - **Content:** Detailed steps, troubleshooting tips, or explanations
+3. Click **Save** to create the article
+   - The system will automatically assign a KA number (KA001, KA002, etc.)
+4. Click **Cancel** to discard and return to the list
+
+### Editing an Article
+
+1. Open the article you want to edit
+2. Click the **Edit** button
+3. Make your changes to the title or content
+4. Click **Save** to save your changes
+5. Click **Cancel** to discard changes and return to viewing the article
+
+### Deleting an Article
+
+1. Open the article you want to delete
+2. Click the **Delete** button
+3. Confirm that you want to delete the article
+4. The article will be permanently removed
+
+---
+
+## Best Practices
+
+### Writing Good Knowledge Articles
+
+**Use Clear Titles**
+- ✅ "How to Reset User Password in Active Directory"
+- ❌ "Password Thing"
+
+**Structure Your Content**
+- Start with a brief description of the issue or process
+- List steps clearly and in order
+- Include any important warnings or notes
+- Add troubleshooting tips if applicable
+
+**Example Format:**
+```
+Issue: User cannot access shared network drive
+
+Solution:
+1. Verify user has correct permissions
+2. Check network connectivity
+3. Restart Windows File Explorer
+4. If issue persists, check group policy settings
+
+Notes:
+- This issue commonly occurs after Windows updates
+- Always verify the drive is mapped correctly first
+```
+
+**Keep It Updated**
+- When you discover new information or better solutions, edit the article
+- Delete outdated articles that are no longer relevant
+
+**Use Consistent Naming**
+- Keep KA titles consistent (e.g., all start with "How to..." or describe the issue)
+- This makes searching easier
+
+### Search Tips
+
+**Use Keywords**
+- Search for the most unique or specific term
+- Example: Search "VPN" instead of "connection issue"
+
+**Search by KA Number**
+- If you know the KA number, search for it directly (e.g., "KA015")
+- This is the fastest way to find a specific article
+
+**Try Different Terms**
+- If you don't find what you need, try synonyms
+- Example: "login" vs "sign in" vs "authentication"
+
+---
+
+## Common Workflows
+
+### Documenting a New Process
+
+1. Click **+ Create New Article**
+2. Title: "How to [process name]"
+3. Write step-by-step instructions in the content area
+4. Save the article
+5. Share the KA number with your team
+
+### Solving a Recurring Issue
+
+1. Search for existing articles about the issue first
+2. If found: Review the solution and update if needed
+3. If not found: Create a new article documenting the solution
+4. Next time someone has the issue, just search and share the KA number
+
+### Quick Reference During Support Calls
+
+1. While on a support call, search for the relevant issue
+2. Open the article and follow the documented steps
+3. Update the article after the call if you discovered anything new
+
+---
+
+## Troubleshooting
+
+### "No articles found"
+- Check your search term - try a broader search
+- Clear the search box to see all articles
+- If truly no articles exist, create the first one!
+
+### Can't save an article
+- Make sure you've entered a title (content is optional)
+- Check that the backend server is running
+- Refresh the page and try again
+
+### Article list not updating after creating/editing
+- Refresh the browser page
+- Check that both frontend and backend are running
+
+### Server won't start
+- Make sure port 9000 is not in use by another application
+- Check that all dependencies are installed (`npm install` in the server folder)
+
+---
+
+## Technical Details
+
+### Data Storage
+- All articles are stored in a local SQLite database (`ka.db`)
+- Located in the server folder
+- **Important:** Back up this file regularly to prevent data loss
+
+### System Requirements
+- Node.js installed
+- Modern web browser (Chrome, Firefox, Edge)
+- Ports 9000 (backend) and 5173 (frontend) available
+
+### Backing Up Your Knowledge Base
+
+**Manual Backup:**
+1. Stop the backend server
+2. Copy the `ka.db` file to a backup location
+3. Restart the server
+
+**Recommended Schedule:**
+- Weekly backups at minimum
+- Daily backups if creating/editing articles frequently
+
+### Restoring from Backup
+
+1. Stop the backend server
+2. Replace `ka.db` with your backup copy
+3. Restart the server
+4. Refresh the frontend
+
+---
+
+## Quick Reference
+
+| Action | How To |
+|--------|--------|
+| Search | Type in the search bar at the top |
+| View article | Click on an article in the list |
+| Create new | Click "+ Create New Article" button |
+| Edit | Open article → Click "Edit" |
+| Delete | Open article → Click "Delete" → Confirm |
+| Go back | Click "← Back" button |
+
+---
+
+## Need Help?
+
+Since this is an internal tool for our IT team:
+- Ask a team member who has used it before
+- Check this guide for common tasks
+- If you find a bug or have a feature request, let Matt know
+
+---
+
+## Version History
+
+- **v0.0.1 (MVP)** - Basic CRUD operations, search functionality
+  - Create, view, edit, delete articles
+  - Search by title, content, or KA number
+  - Auto-generated KA numbers