trackaccess/README.md

# 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