Next.js API: Chemistry Endpoints
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The cheMD project utilizes a set of Next.js API routes to handle complex chemical data processing, structure management, and rendering tasks. These endpoints serve as the bridge between the frontend playground and the core chemistry packages, enabling features such as SMILES normalization, structure saving, and high-fidelity rendering of molecular objects.
The API architecture is designed to support a multi-stage pipeline where raw Markdown or chemical identifiers are transformed into structured Semantic AST nodes, validated against chemistry rules, and finally converted into visual or machine-readable formats.
Sources: chemd-v0.1-architecture.md:52-66, apps/web/src/app/page.tsx:215-236
Core API Infrastructure
Structure and Session Management
API interactions within the web application are often associated with a sessionId and a documentId to maintain state during editing sessions, particularly when interfacing with structure editors like Ketcher.
Sources: apps/web/src/app/page.tsx:88-89, apps/web/src/app/page.tsx:218-223
This diagram illustrates the typical communication flow when a user saves a chemical structure from the UI.
Sources: apps/web/src/app/page.tsx:215-245
Key API Endpoints
| Endpoint | Method | Purpose | Key Parameters |
|---|---|---|---|
/api/chem/structure/save | POST | Persists chemical structures (SMILES/Molfile) and returns normalized versions. | documentId, blockId, sessionId, smiles, molfile |
/api/chem/normalize | POST | Normalizes chemical identifiers or SMILES strings. | smiles, type |
/api/chem/render | POST/GET | Generates visual assets (SVG) based on render profiles and molecular data. | smiles, profileId, options |
Sources: apps/web/src/app/page.tsx:215-224, chemd-v0.1-architecture.md:270-285
Processing Pipeline Logic
The Normalization and Resolution Layer
The API leverages the @chemd/resolver and @chemd/parser packages to ensure that data sent to the endpoints conforms to the cheMD specification. This involves building an object index and resolving references (e.g., @meta.key or @id.field) before data is persisted or rendered.
Sources: chemd-v0.1-architecture.md:144-156, chemd-v0.1-spec.md:500-515
The flow above represents the internal logic performed by the backend resolution layer used by the API routes.
Sources: chemd-v0.1-architecture.md:162-184
Rendering and Profiles
The /api/chem/render endpoint is responsible for generating visual output. It consumes a RenderOptions object which includes bond lengths, line widths, and color modes. Crucially, these style properties are kept separate from the semantic chemical data.
Sources: chemd-v0.1-architecture.md:225-245, chemd-v0.1-spec.md:118-135
Render Option Configuration
| Option | Type | Description |
|---|---|---|
bondLength | number | Fixed length for chemical bonds in pixels/units. |
bondLineWidth | number | Thickness of bond lines. |
monochrome | boolean | Whether to render in black and white. |
imageFormat | "svg" | "png" | The target output format for the rendering engine. |
Sources: chemd-v0.1-architecture.md:230-244, chemd-v0.1-spec.md:118-135
Integration with External Tools
The API acts as a bridge for external tools such as:
- RDKit.js: Primary engine for structure-to-SVG generation.
- Ketcher: Used via a dialog in the web app, communicating with the
/structure/saveendpoint to update molecule blocks. - OCR Service: Processes uploaded images and returns SMILES strings to be injected into the document source via the API.
Sources: chemd-v0.1-architecture.md:300-315, apps/web/src/app/page.tsx:215-245, apps/web/src/app/page.tsx:112-126
Conclusion
The Next.js API endpoints in cheMD provide the necessary infrastructure to manage the lifecycle of chemical data within a Markdown environment. By separating semantic data resolution from visual rendering logic, these endpoints ensure that the underlying document remains a stable, plain-text source of truth while supporting advanced features like real-time previewing, structure editing, and automated normalization.