API Backend Architecture (NestJS)
Relevant source files
The following files were used as context for generating this wiki page:
The Ever Rec API is a backend server built with the NestJS framework and TypeScript. It serves as the central API for the entire Ever Rec platform, including the web portal, browser extensions, and desktop application. The API is responsible for handling business logic, data persistence with Firebase, user authentication, and integration with third-party services. It is part of a Turborepo-managed monorepo.
The architecture is modular, with features encapsulated into distinct NestJS modules. It relies on environment variables for configuration, supports Swagger for API documentation, and uses WebSockets for real-time communication.
Sources: README.md, apps/api/package.json, apps/api/src/app.module.ts
Core Technologies
The API backend is built upon a modern stack centered around Node.js and NestJS.
| Technology/Library | Description |
|---|---|
| NestJS | A progressive Node.js framework for building efficient, reliable, and scalable server-side applications. |
| TypeScript | The primary language, providing static typing for better code quality and maintainability. |
| Firebase (Admin SDK) | Used for backend services, including authentication and what appears to be a Realtime Database for data storage. |
| Express | The underlying HTTP server framework used by NestJS. |
| Swagger (OpenAPI) | For generating interactive API documentation. |
| Sentry | For error monitoring and reporting. |
Axios / nestjs-http-promise | For making HTTP requests to external services. |
Sources: apps/api/package.json, README.md, apps/api/src/main.ts:4
Application Bootstrap
The application entry point is apps/api/src/main.ts. The bootstrap function initializes and configures the NestJS application.
The following diagram illustrates the startup sequence of the API server.
Sources: apps/api/src/main.ts:12-69
Key Bootstrap Steps:
- Application Creation: An instance of the NestJS application is created from
AppModuleusingNestFactory.create.
Sources: apps/api/src/main.ts:13 - Configuration: The
ConfigServiceis retrieved to access environment variables.
Sources: apps/api/src/main.ts:15 - Static Assets: A
publicdirectory is configured to serve static files.
Sources: apps/api/src/main.ts:27-36 - Global Prefix: All API routes are prefixed with
api/v1.
Sources: apps/api/src/main.ts:38 - CORS: Cross-Origin Resource Sharing is enabled to allow requests from the web portal's URL, which is specified by the
WEBSITE_URLenvironment variable.
Sources: apps/api/src/main.ts:40-44 - Body Parser: The application is configured to handle large payloads (
50mblimit) for both JSON and URL-encoded bodies.
Sources: apps/api/src/main.ts:49-57 - Swagger Documentation: An OpenAPI (Swagger) specification is generated from the controllers and DTOs. The interactive documentation is available at the
/docsendpoint.
Sources: apps/api/src/main.ts:60-66 - Listening Port: The server starts listening for incoming requests on the port defined by the
API_PORTenvironment variable, defaulting to3000.
Sources: apps/api/src/main.ts:46, 68
Modular Architecture
The API follows the modular design pattern encouraged by NestJS. The root module, AppModule, imports all feature modules, providing a clear overview of the application's capabilities.
This diagram shows the high-level feature modules that constitute the API.
Sources: apps/api/src/app.module.ts:25-49
Core Modules
| Module | Description |
|---|---|
AuthModule | Handles user authentication and authorization. |
FirebaseModule | Provides integration with Firebase services. |
ImageModule | Manages image uploads, storage, and manipulation. |
VideoModule | Manages video uploads, processing, and storage. |
WorkspaceModule | Contains logic for workspace and team management. |
AtlassianModule | Integrates with Atlassian products like Jira and Trello. |
SlackModule | Handles integration with Slack. |
DropboxModule | Manages file operations with Dropbox. |
DriveModule | Manages file operations with Google Drive. |
EditorWebsocketModule | Provides real-time functionality via WebSockets, likely for collaborative editing. |
LogModule | Handles application logging, possibly including analytics events. |
WhiteboardsModule | Manages functionality related to digital whiteboards. |
Sources: apps/api/src/app.module.ts:25-49
Configuration Management
The application uses the @nestjs/config module for managing environment variables. Configuration is loaded from a .env file based on the NODE_ENV variable. For production, it uses .env, and for development, it uses .env.dev.
Sources: apps/api/src/app.module.ts:27-30
Key Environment Variables
| Variable | Description |
|---|---|
FIREBASE_API_KEY | API key for the Firebase project. |
FIREBASE_PROJECT_ID | Project ID for the Firebase project. |
FIREBASE_ADMIN_PRIVATE_KEY | Private key for the Firebase Admin SDK service account. |
FIREBASE_ADMIN_CLIENT_EMAIL | Client email for the Firebase Admin SDK service account. |
WEBSITE_URL | The base URL of the frontend portal, used for CORS configuration. |
API_PORT | The port on which the API server will run. Defaults to 3000. |
JIRA_CLIENT_ID | Client ID for Jira OAuth integration. |
JIRA_CLIENT_SECRET | Client secret for Jira OAuth integration. |
TRELLO_KEY | API key for Trello integration. |
Sources: README.md, apps/api/src/main.ts:41, 46, apps/api/src/services/atlassian/atlassian.api.service.ts:31-32, 37
API Endpoints and Routing
All API routes are globally prefixed with /api/v1. The routes are defined within the controllers of each module. For example, workspace-related endpoints are found under /api/v1/workspace/.
Example Endpoints
| Method | Path | Description |
|---|---|---|
POST | /api/v1/workspace/new?name={name} | Creates a new workspace. |
GET | /api/v1/workspace/all | Retrieves all workspaces for the authenticated user. |
POST | /api/v1/workspace/{workspaceId}/files/image | Uploads an image to a specific workspace. |
POST | /api/v1/atlassian/jira/create/issue | Creates a new issue in Jira. |
GET | /api/v1/atlassian/jira/sign-in | Generates the OAuth URL for Jira authentication. |
Sources: apps/portal/app/services/api/workspace.ts, apps/extensions/src/app/services/api/messages.ts, apps/api/src/main.ts:38
External Service Integration: Atlassian (Jira)
The API integrates with external services like Jira to provide extended functionality. The AtlassianModule and its associated services (AtlassianService, AtlassianApiService) handle this.
Jira Authentication Flow
The integration uses an OAuth 2.0 authorization code grant flow. The sequence diagram below outlines the process for a user to connect their Jira account.
This diagram shows the sequence of calls for Jira OAuth authentication.
Sources: apps/api/src/module/atlassian/atlassian.service.ts:114-153, apps/api/src/services/atlassian/atlassian.api.service.ts:74-105, 122-125
Once authenticated, the API can perform actions on behalf of the user, such as creating issues and adding attachments. The service includes logic to handle token expiration and use the refresh_token to obtain a new access_token.
Sources: apps/api/src/services/atlassian/atlassian.api.service.ts:200-234