Akita

Introduction

Akita is the web frontend for DataCite Commons, a discovery service that connects research outputs, people, and organizations. It provides a unified search interface to explore the research landscape using persistent identifiers (PIDs).

Key features include:

• Works Search: Discover research outputs (datasets, software, text, etc.) via DOIs.
• People Search: Find researchers and their contributions via ORCID IDs.
• Organization Search: Explore research institutions and their outputs via ROR IDs.
• Repository Search: Find data repositories via DataCite Client IDs and re3data IDs.
• Visualization: View connections and statistics related to research entities.

Tech Stack

• Frontend: Next.js (React framework), @tanstack/react-query (data fetching), React Bootstrap (UI components).
• Backend: Flask (Python microframework) for specific API endpoints.
• Testing: Cypress (End-to-End testing).

Project Structure

• api/: Python Flask application for backend services (e.g. related works graph).
• src/: Main source code for the Next.js frontend.
  • app/: Next.js App Router pages/routes.
  • components/: Reusable React components.
  • data/: REST query modules, constants, and data fetching logic.
• cypress/: End-to-End tests.
• public/: Static assets.

Prerequisites

You will need the following things properly installed on your computer.

• Git
• Node.js 22+ (includes Corepack) — a version manager like N, mise, or asdf works well
• Python 3.12+
• uv — required by the api and api-prod scripts (uv sync / uv run); install with pip3 install uv or see the uv install guide

This repo pins Yarn 4 via the packageManager field in package.json. You do not need a global Yarn 1 install.

Installation

• git clone <repository-url> this repository
• corepack enable
• yarn install
• cp .env.example .env (and configure environment variables as needed)

The api and api-prod scripts run uv sync --project api and uv run --project api to install and start the Flask API. yarn dev-all runs yarn api alongside the frontend, so uv must be installed for local full-stack development. The first yarn api or yarn dev-all will sync Python dependencies automatically.

Environment Variables

The application uses several environment variables for configuration. You can set these in a .env file in the root directory. A .env.example file is provided as a template.

Variable	Description	Default (if not set)
NEXT_PUBLIC_API_URL	DataCite API URL	https://api.stage.datacite.org
NEXT_PUBLIC_PROFILES_URL	DataCite Profiles URL	https://profiles.stage.datacite.org
NEXT_PUBLIC_ORCID_API_URL	ORCID API URL	https://pub.sandbox.orcid.org/v3.0
NEXT_PUBLIC_ID_BASE	Base URL for DOI resolution	https://handle.stage.datacite.org/
NEXT_PUBLIC_GA_TRACKING_ID	Google Analytics Tracking ID	-
SENTRY_DSN	Sentry DSN for error tracking	-
NEXT_PUBLIC_FEATURE_FLAGS	Comma-separated list of feature flags	-

Running / Client

• yarn dev-all (runs both Next.js frontend and Python API)
• Visit your app at http://localhost:3000.

Note: yarn dev only runs the frontend. If you need the API, use yarn dev-all or run yarn api in a separate terminal.

Running / Server

• yarn build
• yarn start
• Visit your app at http://localhost:3000.

Running Tests

• yarn cy:run: Runs Cypress tests in headless mode.
• yarn cy:open: Opens the Cypress Test Runner for interactive testing.

Linting and Formatting

• yarn lint: Runs ESLint to check for code quality issues.
• yarn prettier-format: Formats code using Prettier.
• yarn type-check: Runs TypeScript compiler to check for type errors.

Deploying

The application is built and deployed using Vercel and GitHub Actions

Contributing

1. Fork the project.
2. Create a feature branch (git checkout -b feature/my-new-feature).
3. Commit your changes (git commit -am 'Add some feature').
4. Push to the branch (git push origin feature/my-new-feature).
5. Create a new Pull Request.

Please ensure you:

• Write tests for new features or bug fixes.
• Follow the existing code style.
• Do not modify the Rakefile, version, or history files directly (if applicable).

Resources

• DataCite Commons: The live service.
• DataCite API Documentation: Reference for the DataCite REST API.
• DataCite GraphQL API Guide: Used server-side only for DOI claims via the /claims route handlers.
• DataCite Support: General support documentation.

License

akita is released under the MIT License.