Backend: API Endpoints

Relevant source files

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

• server/lambda.ts
• server/common/account/account.endpoints.ts
• server/common/oauth/oauth.endpoints.ts
• server/common/sync/down/index.ts
• server/common/sync/up/index.ts
• WARP.md
• README.md
• client/landing/shared/faqs.data.ts
• client/cx/contemporaries/obsidian.json
• test-setup.js

The Nucleus backend is a Node.js application responsible for handling core business logic, including user authentication, account management, payment processing, and data synchronization. It is designed to be deployed as a serverless function, as indicated by the lambda.ts entry point, likely targeting platforms like AWS Lambda or Cloudflare Workers.

The API is built using the Hono web framework, which provides a lightweight and fast routing mechanism. The backend's primary responsibilities are to serve as a secure interface for client applications (Nucleus, Memotron, etc.) to manage user data and to orchestrate the synchronization of data across multiple devices, ensuring a consistent user experience.

Sources: server/lambda.ts, README.md

API Architecture

The backend architecture is modular, with different functionalities encapsulated in separate endpoint files. The main entry point, server/lambda.ts, uses Hono's route method to delegate requests to the appropriate handlers based on the URL path. This creates a clean separation of concerns for different parts of the API.

The primary API routes are:

• /account: Manages user account details and billing.
• /oauth: Handles third-party authentication flows (e.g., Google).
• /sync: Manages data synchronization between the client and server.

Sources: server/lambda.ts:10-14

The following diagram illustrates the high-level request routing flow.

Sources: server/lambda.ts:10-14

Endpoints

Account Management (/account)

These endpoints are responsible for user account operations, including fetching account data, deleting an account, and managing billing through Stripe.

Sources: server/common/account/account.endpoints.ts

Endpoint	HTTP Method	Description
/	GET	Fetches the current authenticated user's account details.
/	DELETE	Deletes the user's account and signs them out.
/checkout	POST	Creates a Stripe checkout session for subscriptions.
/portal	GET	Creates a Stripe billing portal session for the user to manage their subscription.

Sources: server/common/account/account.endpoints.ts:10-41

OAuth Authentication (/oauth)

This set of endpoints manages the authentication flow using third-party OAuth providers. Currently, it implements the callback for Google OAuth.

Sources: server/common/oauth/oauth.endpoints.ts

Endpoint	HTTP Method	Description
/google/callback	GET	Handles the server-side part of the Google OAuth 2.0 flow after the user grants permission.

Sources: server/common/oauth/oauth.endpoints.ts:13-52

The Google OAuth callback sequence is as follows:

1. The client is redirected from Google to /oauth/google/callback with a code and state.
2. The server validates the authorization code with Google to get access tokens.
3. It fetches the user's profile from Google.
4. It checks if a user with this Google ID already exists in the database.
5. If the user exists, a new session is created. If not, a new user record is created first, and then a session is created.
6. Finally, the user is redirected to the /sync page within the application.

This flow is visualized in the sequence diagram below.

Sources: server/common/oauth/oauth.endpoints.ts:13-52

Data Synchronization (/sync)

The /sync endpoints are the core of the data synchronization mechanism, allowing clients to push local changes to the server and pull remote changes.

Up Sync (/sync/up)

The up-sync endpoint receives a batch of changes from a client and processes them to update the server-side state.

Sources: server/common/sync/up/index.ts

Endpoint	HTTP Method	Description
/	POST	Receives a batch of client-side changes (IBatch) and processes them. Returns a new server version number.

Sources: server/common/sync/up/index.ts:10-15

The up-sync process is as follows:

1. The client sends a POST request to /sync/up with a payload containing a batch of data changes.
2. The API authenticates the user.
3. The processBatch function is called with the user's identity and the batch data.
4. After processing, the server returns a new version number, confirming the update.

Sources: server/common/sync/up/index.ts:10-15

Down Sync (/sync/down)

The down-sync endpoint allows a client to fetch all changes that have occurred on the server since its last sync.

Sources: server/common/sync/down/index.ts

Endpoint	HTTP Method	Description
/	GET	Fetches changes from the server based on the client's last known version, passed as a version query parameter.

Sources: server/common/sync/down/index.ts:10-15

The down-sync process is as follows:

1. The client sends a GET request to /sync/down?version=<last_client_version>.
2. The API authenticates the user.
3. The getUpdates function is called with the user's ID and the provided version number.
4. This function queries the database for all changes that occurred after the client's version.
5. The server responds with a payload containing the batch of changes and the latest server version number.

Sources: server/common/sync/down/index.ts:10-15

Conclusion

The Nucleus backend API provides a well-structured and secure interface for essential application services. By leveraging Hono for routing and organizing logic into distinct modules for account management, authentication, and data synchronization, the system maintains a clean and scalable architecture. The serverless design ensures efficient resource utilization, while the robust sync mechanism enables a seamless multi-device experience for users.

Sources: server/lambda.ts, server/common/sync/up/index.ts, server/common/sync/down/index.ts