> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meridian.study/llms.txt
> Use this file to discover all available pages before exploring further.

# Compass Frontend Development

> Frontend architecture for utilization, scheduling, and space surfaces

# Compass Frontend Development

The Compass-facing UI is built with **React** inside the shared Meridian frontend. It emphasizes **utilization, scheduling, and booking**—how users find time in space and how operators see load—alongside Compass-specific reporting surfaces.

## Overview

Code lives under `Meridian/frontend/` together with Atlas and Beacon; Compass is a domain slice of that app, not a separate repository. Platform-wide web conventions (`useFetch`, `postRequest`, shared layout) are in **[Web client best practices](/frontend/best-practices)**.

### Key Technologies

* **React** - UI framework
* **SCSS** - Styling
* **Context API** - State management
* **React Router** - Navigation
* **WebSocket** - Real-time updates

## Component Structure

### Core Components

```
frontend/src/
├── components/
│   ├── CalendarComponents/    # Calendar views for room booking
│   │   ├── Calendar.jsx
│   │   ├── DayColumn.jsx
│   │   └── MobileCalendar.jsx
│   ├── Classroom/            # Room detail views
│   │   ├── Classroom.jsx
│   │   ├── CheckedIn.jsx
│   │   └── RatingGraph.jsx
│   ├── SearchBar/            # Room search functionality
│   └── Popup/                # Modal dialogs
├── pages/
│   ├── Classroom.jsx         # Room detail page
│   └── CreateEvent.jsx       # Event creation
└── context/
    ├── AuthContext.js        # User authentication
    ├── CacheContext.js       # API caching
    └── WebSocketContext.js  # Real-time updates
```

## Key Features

### Room Discovery

The search and discovery interface allows users to:

* Browse available rooms by location, capacity, and amenities
* View real-time availability calendars
* Filter by specific requirements (projector, whiteboard, etc.)
* See ratings and reviews from other users

### Booking System

```jsx theme={null}
// Example booking component
import { useAuth } from '../context/AuthContext';
import { useWebSocket } from '../context/WebSocketContext';

const BookingComponent = () => {
  const { user } = useAuth();
  const { sendMessage } = useWebSocket();
  
  const handleBooking = async (roomId, timeSlot) => {
    // Booking logic
    await bookRoom(roomId, timeSlot);
    sendMessage('booking_created', { roomId, timeSlot });
  };
  
  return (
    // Booking UI
  );
};
```

### Real-time Updates

Compass uses WebSocket connections to provide:

* Live availability updates
* Instant booking confirmations
* Real-time occupancy status
* Notification of room changes

## State Management

### Context Providers

**AuthContext**: Manages user authentication and session

```jsx theme={null}
const { user, login, logout } = useAuth();
```

**CacheContext**: Caches API responses for performance

```jsx theme={null}
const { getCached, setCache } = useCache();
```

**WebSocketContext**: Handles real-time connections

```jsx theme={null}
const { isConnected, sendMessage, subscribe } = useWebSocket();
```

## Routing

Key routes for Compass:

* `/` - Landing page with room search
* `/classroom/:id` - Room detail page
* `/create-event` - Event creation with room booking
* `/feature-admin/compass` - Admin dashboard for Compass

## Styling Guidelines

Compass uses SCSS with BEM naming convention:

```scss theme={null}
.Classroom {
  &__header {
    font-size: 1.5rem;
    margin-bottom: 1rem;
  }
  
  &__details {
    display: flex;
    gap: 1rem;
  }
  
  &--featured {
    border: 2px solid var(--primary-color);
  }
}
```

## Development Workflow

1. **Start Development Server**
   ```bash theme={null}
   cd Meridian/frontend
   npm start
   ```

2. **Make Component Changes**
   * Edit files in `src/components/`
   * Changes auto-reload via hot module replacement

3. **Test Components**
   ```bash theme={null}
   npm test
   ```

## Best Practices

* **Component Reusability**: Create reusable components for common UI patterns
* **Performance**: Use React.memo for expensive components
* **Accessibility**: Follow WCAG guidelines for inclusive design
* **Error Handling**: Implement error boundaries for graceful failures

## Integration Points

* **Backend API**: RESTful endpoints for room and event data
* **WebSocket Server**: Real-time updates and notifications
* **Calendar Systems**: External calendar integration
* **Authentication**: SAML/OAuth for user login

## Related pages

<CardGroup cols={2}>
  <Card title="Compass overview" icon="compass" href="/compass/overview">
    Product scope, utilization concepts, and how Compass reporting differs from Atlas/Beacon.
  </Card>

  <Card title="Web client best practices" icon="code" href="/frontend/best-practices">
    Shared Meridian frontend patterns: routing, state, and API access.
  </Card>

  <Card title="API reference" icon="book" href="/api-reference/introduction">
    HTTP APIs the Compass UI and integrations call.
  </Card>

  <Card title="Authentication overview" icon="shield" href="/backend/auth/overview">
    How campus users sign in and how tokens flow to Compass clients.
  </Card>

  <Card title="Development" icon="wrench" href="/development">
    Local dev server, WebSockets, and troubleshooting for real-time features.
  </Card>

  <Card title="Backend best practices" icon="server" href="/backend/best-practices">
    How Compass-facing routes use `req.db` and shared middleware.
  </Card>
</CardGroup>