Add README with app description and setup instructions

Document the TrackAccess application including features, tech stack, database schema, configuration, and API endpoints. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-26 17:12:41 -05:00
parent 6a61776a4f
commit 1e2a04d519
1 changed files with 154 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,154 @@
+# TrackAccess
+
+A web application for tracking and managing user access to systems across an organization. Administrators can define department roles, access levels, and assign system access to users based on their roles.
+
+## Features
+
+- **Department Roles**: Define departments and roles within your organization
+- **Access Levels**: Configure available access levels (e.g., Read, Write, Admin)
+- **Users**: Manage user records
+- **User Roles**: Assign users to department roles
+- **Access Records**: Track which systems users can access, including access level, local account info, and additional access notes
+- **Reporting**: View, filter, sort, and export access data to CSV
+
+## Tech Stack
+
+**Frontend:**
+- React 19
+- React Router
+- Bootstrap 5
+- Vite
+
+**Backend:**
+- Node.js with Express 5
+- MySQL (via mysql2)
+- JWT authentication
+
+## Project Structure
+
+```
+trackaccess/
+├── backend/
+│   ├── server.js          # Express API server
+│   ├── db.js              # MySQL connection pool
+│   ├── middleware/auth.js # JWT authentication middleware
+│   └── package.json
+└── frontend/
+    ├── src/
+    │   ├── App.jsx        # Main app with routing
+    │   ├── api.js         # API client
+    │   └── components/    # React components
+    └── package.json
+```
+
+## Setup
+
+### Prerequisites
+
+- Node.js 18+
+- MySQL 8+
+
+### Database Setup
+
+Create a MySQL database and the following tables:
+
+```sql
+CREATE DATABASE trackaccess;
+USE trackaccess;
+
+CREATE TABLE DepartmentRoles (
+  DepartmentRoleId INT AUTO_INCREMENT PRIMARY KEY,
+  department VARCHAR(255) NOT NULL,
+  role VARCHAR(255) NOT NULL
+);
+
+CREATE TABLE AccessLevels (
+  access_level VARCHAR(50) PRIMARY KEY
+);
+
+CREATE TABLE Users (
+  UserId INT AUTO_INCREMENT PRIMARY KEY,
+  name VARCHAR(255) NOT NULL
+);
+
+CREATE TABLE UserRoles (
+  UserRoleId INT AUTO_INCREMENT PRIMARY KEY,
+  UserId INT NOT NULL,
+  DepartmentRoleId INT NOT NULL,
+  FOREIGN KEY (UserId) REFERENCES Users(UserId),
+  FOREIGN KEY (DepartmentRoleId) REFERENCES DepartmentRoles(DepartmentRoleId)
+);
+
+CREATE TABLE AccessRecords (
+  RecordId INT AUTO_INCREMENT PRIMARY KEY,
+  UserRoleId INT NOT NULL,
+  system_name VARCHAR(255) NOT NULL,
+  access_level VARCHAR(50) NOT NULL,
+  local_account VARCHAR(255),
+  additional_access TEXT,
+  FOREIGN KEY (UserRoleId) REFERENCES UserRoles(UserRoleId),
+  FOREIGN KEY (access_level) REFERENCES AccessLevels(access_level)
+);
+```
+
+### Backend Configuration
+
+Create a `.env` file in the `backend/` directory:
+
+```env
+PORT=4000
+DB_HOST=localhost
+DB_USER=your_mysql_user
+DB_PASSWORD=your_mysql_password
+DB_NAME=trackaccess
+JWT_SECRET=your_secret_key
+ADMIN_USER=admin
+ADMIN_PASS=your_admin_password
+```
+
+### Installation
+
+```bash
+# Install backend dependencies
+cd backend
+npm install
+
+# Install frontend dependencies
+cd ../frontend
+npm install
+```
+
+### Running the Application
+
+```bash
+# Start the backend (from backend/)
+npm start
+
+# Start the frontend (from frontend/)
+npm run dev
+```
+
+The frontend runs on `http://localhost:5173` and the backend API on `http://localhost:4000`.
+
+## API Endpoints
+
+All endpoints except `/api/login` require JWT authentication via `Authorization: Bearer <token>` header.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/login` | Authenticate and receive JWT token |
+| GET/POST/PUT/DELETE | `/api/departmentroles` | Manage department roles |
+| GET/POST/PUT/DELETE | `/api/accesslevels` | Manage access levels |
+| GET/POST/PUT/DELETE | `/api/users` | Manage users |
+| GET/POST/DELETE | `/api/userroles` | Manage user-to-role assignments |
+| GET/POST/PUT/DELETE | `/api/accessrecords` | Manage access records |
+
+## Usage
+
+1. Log in with the admin credentials configured in your `.env` file
+2. Set up **Department Roles** (e.g., "IT" + "Administrator", "Finance" + "Analyst")
+3. Define **Access Levels** (e.g., "Read Only", "Read/Write", "Full Access")
+4. Add **Users** to the system
+5. Assign users to department roles via **User Roles**
+6. Create **Access Records** to document which systems each user-role can access
+7. Use the **Report** tab to view, filter, and export access data