nextspace
    Preparing search index...

    nextspace

    About Nextspace

    This repo is for the Nextspace frontend. It uses React, Typescript, and Next.js. Production is hosted on Vercel. For more info on the Nextspace backend, check out LLM Engine.

    Nextspace uses a hybrid authentication model that supports both anonymous participation and authenticated administrative access.

    Guest (authType="guest")

    • Automatically created when users visit most pages
    • Assigned a pseudonym (e.g., "Gentle Deer", "Brave Fox") for participation in conversations
    • No login required - sessions are created automatically in the background
    • Can access public pages and participate in events
    • Session persists via encrypted cookie for 30 days

    Admin (authType="admin")

    • Requires explicit login with username and password via /login
    • Full access to administrative routes (/admin/*)
    • Can create and manage events, configure agents, view analytics
    • Non-admin users attempting to access /admin routes are redirected to signup

    User (authType="user")

    • Planned for future implementation
    • Would represent authenticated users without admin privileges
    • Currently not fully implemented in the application

    1. Guest Sessions: When a user visits Nextspace, SessionManager automatically creates a guest session with a pseudonymous identity. This allows users to participate in conversations without creating an account.

    2. Admin Authentication: Administrators log in through /login with credentials. Upon successful authentication, the session cookie is updated with authType: "admin", granting access to administrative features.

    3. Session Management: All sessions (guest and admin) are stored in encrypted HTTP-only cookies using JWT with A128CBC-HS256 encryption. The middleware.ts file validates these cookies and sets the appropriate x-auth-type header for each request.

    4. Route Protection: The middleware automatically:

      • Redirects unauthenticated users from /admin routes to /signup
      • Allows guest access to public routes
      • Validates admin credentials for protected routes
    • Guest pseudonyms are for participation, not authentication
    • Session cookies are encrypted and HTTP-only for security
    • Certain pages (home, login, signup, logout) skip automatic guest session creation to avoid unnecessary accounts
    • The SESSION_SECRET environment variable must be at least 32 characters for secure cookie encryption

    This view displays what an event moderator uses when assessing insights and metrics that are being generated by participant questions and feedback. If the event has enabled it and it is provided in the URL as a parameter, a transcript view is also visible. The ModeratorScreen function initially attempts to authenticate the user and retrieves an API token, and if successful initializes the socket connection. This socket listens for "message:new" and acts on it as needed.

    This view displays what an event participant uses to send in questions and feedback during an event that uses only the Back Channel agent. The nomenclature for this channel being utilized is currently a "backchannel". The BackchannelRoom function initially attempts to register a new pseudonym for the session and sets local API tokens, if successful. It then joins the socket.io instance and the relevant conversation. The SendData utility function is used here to send messages from the user to the API.

    This view is for event participants to interact with Event Assistant or Event Assistant Plus. It provides an interface to send and receive direct messages with the agent, and with Event Assistant Plus, to send messages to the moderator. If the event has enabled it and it is provided in the URL as a parameter, a transcript view is also visible.

    Detailed repo structure

    This project uses the Next.js Pages Router.

    • components/ Frontend components used across the app; see docs/ for a detailed breakdown of each component.

    • docs/ Auto-generated static HTML files for code documentation.

    • hooks/ Custom React hooks used across the app.

      • useAnalytics.ts Hook for tracking session-level analytics (session start/end, page views, active time).
      • useAutoScroll.ts Hook for automatically scrolling to bottom of message lists.
      • useVisibilityAwareDuration.ts Hook for tracking time spent on a page while visible (excludes time when tab is hidden).

    • pages/ Next.js pages for the app.

      • admin/[type]/ Administration tools; see dynamic segments in Next.js.
        • [id].tsx Checks the [id] and [type] and renders an Event component.
        • view/
          • [id].tsx Checks the [id] and renders an EventStatus component.
      • api/ Client-side public API routes; see Next.js docs
        • check-location.ts Route to detect if user is connecting from local or remote IP address.
        • cookie.ts Route to see if user has stored cookie and then decrypt it, return tokens and user info.
        • logout.ts Route to handle user logout by clearing the session cookie.
        • request.ts Route to handle requests with authentication.
        • session.ts Route to handle setting the session cookie upon user login.
      • _app.tsx Custom App file to initialize all pages; see Next.js docs.
      • _document.tsx Custom Document used to render pages; see Next.js docs.
      • login.tsx Renders the login page for users to authenticate.
      • logout.tsx Handles the logout process by clearing session and redirecting to login.
      • moderator.tsx Render the moderator view; see "App views overview".
      • backchannel.tsx Render the backchannel (participant) view; see "App views overview".
      • assistant.tsx Render the assistant (participant) view; see "App views overview".
      • signup.tsx Allows users to create an account with username, email, and password.

    • utils/ Various utilities used across the app; see docs/ for a detailed breakdown of each method.

      • analytics.ts Matomo analytics integration for tracking events, page views, and custom dimensions.
      • Api.ts Helper methods for fetching data from the LLM Engine API.
      • Decrypt.ts Decrypts a JWT token to retrieve cookie payload.
      • ErrorHandler.ts Checks if router query parameters are valid.
      • Helpers.ts General data-handling methods.
      • ipRangeChecker.ts Checks if IP addresses are within specified CIDR ranges for location detection.
      • SessionManager.ts Singleton that manages session state across the app. Automatically restores sessions from encrypted cookies on app initialization, creates guest sessions for new users, and handles transitions between guest and authenticated states. Certain pages (home, login, signup, logout) skip session creation to avoid unnecessary guest accounts.
      • useSessionJoin.ts Hook for initializing socket connections with session info from SessionManager.
      • validateEnv.ts Validates required environment variables on app startup.
      • withEnvValidation.ts Higher-order function for API route handlers to validate environment variables.

    Please see the .env.template file to see all available parameters. Copy it to .env and fill in the required values.

    The application will fail to start if any required environment variables are missing, with clear error messages indicating which variables need to be set.

    These variables must be set for the application to run:

    NEXT_PUBLIC_API_URL=<your-backend-url>
      The URL you are using to interact with the backend API, e.g. http://localhost:3000/v1

    NEXT_PUBLIC_SOCKET_URL=<your-socket-url>
      The URL to the socket.io instance, e.g. "ws://localhost:5555/?EIO=4&transport=websocket"

    NEXT_PUBLIC_DEFAULT_TOPIC_ID=<topic-id>
      The ID of the default topic for submitting new events; used within the event creation form

    NEXT_PUBLIC_ABOUT_URL=<about-url>
      The URL for the About page footer link

    SESSION_SECRET=<secret-key>
      Crypto key used to encrypt session cookies with A128CBC-HS256 algorithm
      Must be at least 32 characters (256 bits)
      Generate securely: openssl rand -base64 32
      See https://github.com/panva/jose/issues/210#jwe-alg

    It is strongly recommended that you utilize NVM to initiate the version of node recommended by this repo (the minimum version is node 22.0.0):

    nvm install

    npm install

    npm run openapi-types:generate http://localhost:3000/v1/openapi.json

    This app uses a types file types.ts dynamically generated against the LLM Engine backend server.

    The above example generates types against LLM Engine running locally. You can also provide a URL to a remotely hosted LLM Engine instance if you prefer.

    On default port 8080:

    npm run dev

    OR, to run on a different port if needed

    npm x next -- dev -p <PORT>

    Open http://localhost:8080 with your browser to see the result.

    1. If you would like to run LLM Engine locally, please follow the instructions provided here to get setup.
    2. Interactions with your local backend API will happen via Postman. Import the latest collection and environment for LLM Engine into Postman. Use the “localhost-3000…” environment file if you’re locally running LLM Engine.
    3. Open Postman and run the following requests:
      1. For first-time setup:
        1. Register “test” user (fill in username, password, email with your own test values)
        2. Login “test” user
        3. In the LLM Engine localhost environment, set token to the value of access.token in the login response
      2. Create conversation with channels for moderator/participants
        1. In the response body, you should see a passcode for both the moderator and participant channels (see below for more details)
    4. Before running nextspace locally, be sure to change the NEXT_PUBLIC_LLM_FCLTR_TOPIC_ID in your .env file. The conversation ID can be found in the response body created in 3b. You can also find it in the Environment view in Postman under the “Current value” column.
    5. When running NextSpace locally, you should now be able to access these channels in your local browser.

    Note: A collection of debugging configurations is provided when using VS Code. For help with the debugging in other IDEs or in devtools, see here.

    NextSpace currently uses the following URL convention when loading either the moderator or back channel view: .../<moderator|backchannel>?conversationId=<ID>&channel=<channel,password>

    So a full example of this on your local instance might look like

    http://localhost:8080/moderator?conversationId=688a3f0b435a85b2ee2b80cf5&channel=moderator,6ynQWt7W&channel=transcript,uU0MjlX9

    This would load the moderator view with both the backchannel insights/metrics and transcript.

    The conversationId and passcodes can be found in the response body from step 2b. It should look like this:

       "channels": [
           {
               "_id": "12345678",
               "name": "moderator",
               "passcode": "xxxxxx",
               "__v": 0
           },
           {
               "_id": "12345678",
               "name": "participant",
               "passcode": "xxxxxx",
               "__v": 0
           }
       ],

    The transcript channel password is provided only if you are utilizing one of the API endpoints that includes that as a channel (under "With Transcription" in Postman).

    This repo automatically has changes deployed to Vercel via the Vercel for GitHub app. Changes merged to the main branch will be deployed to production, while any feature branch will automatically be deployed to a preview URL. If you have forked this repo and want to deploy changes without usage of this app, you can do so via the CLI.

    Nextspace includes built-in open source Matomo Tag Manager integration for comprehensive analytics tracking:

    • Session duration and active time measurement
    • Page navigation and engagement tracking
    • User behavior patterns and feature usage
    • Connection status monitoring
    • Mobile vs desktop usage

    The implementation is privacy-friendly (pseudonymized IDs, no message content tracking) and can be easily disabled via environment variable. Analytics gracefully degrades if Matomo isn't configured—the site continues to function normally.

    To disable analytics:

    NEXT_PUBLIC_ENABLE_ANALYTICS=false

    To enable analytics (requires Matomo Tag Manager setup):

    NEXT_PUBLIC_ENABLE_ANALYTICS=true  # or omit (enabled by default)

    Nextspace is AGPL 3.0 licensed.

    Please see CONTRIBUTING.md.

    Settings

    Member Visibility

    On This Page

    About Nextspace