diff --git a/TECHNICAL_DOCUMENTATION.md b/TECHNICAL_DOCUMENTATION.md new file mode 100644 index 0000000..375f8df --- /dev/null +++ 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 diff --git a/USER_GUIDE.md b/USER_GUIDE.md new file mode 100644 index 0000000..9652b77 --- /dev/null +++ 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