Frontend Architecture (Portal & Extension)

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• apps/extensions/package.json
• apps/extensions/src/app/services/api/api.ts
• apps/extensions/src/app/services/api/messages.ts
• apps/extensions/src/content/panel/panel.tsx
• apps/extensions/webpack.config.js
• apps/portal/app/services/api/api.ts
• apps/portal/app/services/api/messages.ts
• apps/portal/package.json
• apps/portal/pages/_app.tsx
• apps/portal/pages/auth/index.tsx

The Ever Rec platform utilizes a monorepo structure to manage two primary frontend applications: a web-based portal (apps/portal) and a browser extension (apps/extensions). Both are built using modern JavaScript technologies, primarily React and TypeScript, and they communicate with a common NestJS backend API. The portal serves as the main web application for managing recordings, storage, and sharing, while the browser extension provides in-browser screen capture and recording functionalities.

This document outlines the architecture of these two frontend applications, detailing their technology stack, structure, build processes, and how they interact with the backend services. Both applications share a similar approach to state management and API communication, but are tailored for their specific environments (web vs. browser extension).

High-Level Structure

The project is organized as a Turborepo monorepo, with the frontend applications located in the apps/ directory.

This diagram shows the high-level project structure within the monorepo.
Sources: README.md:83-88

Technology Stack

Both frontend applications are built on a foundation of React and TypeScript but leverage different frameworks and libraries suited to their specific deployment targets.

Technology	apps/portal (Web App)	apps/extensions (Browser Extension)	Purpose
Framework	Next.js	React	Core UI framework.
UI Library	Ant Design, Tailwind CSS	Ant Design, Tailwind CSS	UI components and styling.
Styling	SASS, CSS Modules	SASS, CSS	CSS preprocessing and component-level styles.
State Management	React-Redux	React-Redux	Global application state management.
API Client	Axios	Axios	HTTP requests to the backend API.
Build Tool	Next.js CLI (next build)	Webpack with esbuild-loader	Bundling and optimizing application assets.
Authentication	@react-oauth/google	gapi-script, google-auth-library	Google OAuth integration.

Sources: README.md:61-70, apps/portal/package.json, apps/extensions/package.json, apps/extensions/webpack.config.js:37-45

Portal Application (apps/portal)

The portal is a full-fledged web application built with Next.js, providing users with a dashboard to manage their media, workspaces, and account settings.

Application Entry Point and Global Context

The main entry point for the portal application is apps/portal/pages/_app.tsx. This file wraps all page components with necessary global providers, including:

• Redux Store: The <Provider> component from react-redux makes the global state available to all components.
• Google OAuth: The <GoogleOAuthProvider> wraps the application to enable Google Sign-In functionality.
• Authentication: A custom Authenticate component likely handles user session validation.
• Toast Notifications: ToastContainer is included for displaying application-wide notifications.
• Global Styles: Imports global SASS/CSS files for consistent styling.

The following diagram illustrates the component hierarchy at the application's root.

API Communication

The portal communicates with the backend via a pre-configured Axios instance defined in apps/portal/app/services/api/api.ts. This instance includes interceptors to manage API requests and responses globally.

• Request Interceptor: Automatically attaches the user's authentication token (retrieved from cookies) to the Authorization header of every outgoing request.
• Response Interceptor: Handles API responses, including error handling. It checks for 401 Unauthorized errors, which may trigger a user logout.

The diagram below shows the sequence of an authenticated API call from the portal.

Browser Extension (apps/extensions)

The browser extension provides core recording features directly within the user's browser. It is built with React and bundled using a custom Webpack configuration.

Build Process and Structure

The extension's build process is defined in apps/extensions/webpack.config.js. It compiles multiple entry points to create the various components of a standard browser extension.

• Entry Points: The configuration defines several JavaScript/TypeScript entry points:
  • background: The background script for event handling.
  • content/content: The content script injected into web pages.
  • popup/popup: The UI for the browser action popup.
  • panel/panel: The main UI panel of the extension.
  • recording/recording: The UI for the recording controls.
• Asset Handling: CopyPlugin is used to copy static assets like manifest.json, icons, images, and HTML files into the final build directory. The manifest.json is transformed to include the package version.
• Loaders: esbuild-loader is used for fast TypeScript/JavaScript compilation, and various loaders handle CSS, SASS, and static assets.

This flowchart shows the Webpack build process for the extension.

Core Components

The extension is composed of several distinct parts that work together:

• Panel (panel.tsx): This is the main user interface of the extension. It is a React application that uses react-router-dom for navigation between different screens (e.g., media, settings, integrations). It is rendered into a DOM element with the ID rec-root-panel.
• Popup (popup.tsx): A smaller React application that likely provides quick actions when the user clicks the extension icon in the browser toolbar.
• Background Script (background.ts): Manages long-running tasks, state, and events, independent of any single browser tab.
• Content Script (content.ts): Injected into web pages to interact with their content, for example, to initiate a screen recording.

Sources: apps/extensions/webpack.config.js:16-22, apps/extensions/src/content/panel/panel.tsx:32-35

API Communication

Similar to the portal, the extension uses a dedicated Axios instance defined in apps/extensions/src/app/services/api/api.ts. The configuration is nearly identical to the portal's, using interceptors to attach the authentication token from localStorage to outgoing requests. This ensures that the extension can make authenticated requests to the backend on behalf of the user.

Sources: apps/extensions/src/app/services/api/api.ts:11-37

Shared API Endpoints

Both the portal and the extension define a set of functions for interacting with specific API endpoints. These are located in their respective services/api/messages.ts files. The functions are largely identical, indicating a shared API contract for features like third-party integrations.

Function	HTTP Method	Endpoint	Description
trelloOauthUrl	GET	/api/v1/atlassian/trello/sign-in	Gets the URL for Trello OAuth authentication.
trelloSaveOauthToken	POST	/api/v1/atlassian/trello/complete-oauth	Saves the Trello OAuth token after successful auth.
trelloDisconnect	DELETE	/api/v1/atlassian/trello/sign-out	Disconnects the user's Trello integration.
createTrelloIssueWithAttachment	POST	/api/v1/atlassian/trello/create/issue	Creates a Trello card with an attachment.
jiraOauthUrl	GET	/api/v1/atlassian/jira/sign-in	Gets the URL for Jira OAuth authentication.
jiraDisconnect	DELETE	/api/v1/atlassian/jira/sign-out	Disconnects the user's Jira integration.
createJiraIssueWithAttachment	POST	/api/v1/atlassian/jira/create/issue	Creates a Jira issue with an attachment.
dropBoxLoginUrl	GET	/api/v1/dropbox/sign-in	Gets the URL for Dropbox authentication.
dropboxDisconnect	DELETE	/api/v1/dropbox/sign-out	Disconnects the user's Dropbox integration.
dropboxUploadFile	POST	/api/v1/dropbox/upload/file	Uploads a file to the user's Dropbox.
saveSegmentEventData	POST	/api/v1/log/segment-event	Logs a Segment analytics event.

Sources: apps/portal/app/services/api/messages.ts, apps/extensions/src/app/services/api/messages.ts

Conclusion

The frontend architecture of Ever Rec is a well-structured system comprising a Next.js-based web portal and a React-based browser extension. Both applications are managed within a single monorepo, share a consistent technology stack, and communicate with the same backend API. They use standardized tools like Axios for API communication with token-based authentication and Redux for state management. This separation allows the portal to offer a comprehensive management experience, while the extension provides focused, in-context functionality, creating a robust and versatile platform for users.