# CelLoc-3D

React single-page application for celloc3d.brain.riken.jp.

CelLoc-3D is a database of the 3D arrangement of neocortical cells (glutamatergic/excitatory, GABAergic/inhibitory
and/or astrocytes) identified in vivo in layer 2/3 of the primary visual cortex of the mouse by two-photon imaging.
The application provides dataset search, dataset detail pages, downloadable data files, and a WebGL-based 3D viewer.

## Tech Stack

| Area | Technology |
| --- | --- |
| Build tool | Vite 8 with `@vitejs/plugin-react` |
| Language | TypeScript 7 |
| UI | React 19, CSS Modules |
| Routing | React Router 8 |
| State management | Redux Toolkit, React Redux |
| HTTP client | ky |
| 3D rendering | three.js |
| Document head | `@dr.pogodin/react-helmet` |
| Analytics | `react-ga4` |
| Lint / format | Biome |
| Spell check | CSpell |

## Requirements

- Node.js `^20.19.0` or `>=22.12.0` (required by Vite 8)
- npm

## Getting Started

Install the dependencies and start the development server:

```sh
npm install
npm run dev
```

Open [http://localhost:5173](http://localhost:5173) to view the application.

## Available Scripts

In the project directory, you can run:

### `npm run dev`

Runs the app in development mode with hot module replacement.<br>
Open [http://localhost:5173](http://localhost:5173) to view it in the browser.

### `npm run build`

Type-checks the project with `tsc -b` and builds the app for production into the `dist` folder.<br>
The build is minified and the filenames include content hashes.

### `npm run preview`

Locally preview the production build.

### `npm run lint`

Run the Biome linter and apply the available fixes.

### `npm run lint:check`

Check for code quality issues without making changes.

### `npm run format`

Run Biome formatter, linter, and import sorting, and apply the available fixes.

### `npm run format:check`

Run the same checks without making changes.

### `npm run spell:check`

Run CSpell over the project files.

## Project Structure

```text
.
├── index.html              # Vite entry HTML
├── vite.config.ts          # Build configuration and manual chunk splitting
├── biome.json              # Formatter and linter configuration
├── cspell.json             # Spell checker dictionary
├── public/
│   ├── data/               # Per-dataset .dat, .json, and .png files
│   └── images/
└── src/
    ├── index.tsx           # Application entry point
    ├── App.tsx             # Layout, navigation, routes, GA initialization
    ├── app/                # Redux store and typed hooks
    ├── assets/             # data.json (dataset index), news.json
    ├── features/           # Feature components, each with its own CSS Module
    └── utils/              # Shared helpers
```

### Routes

| Path | Component | Description |
| --- | --- | --- |
| `/` | `News` | Landing page with news entries |
| `/search` | `SearchForm` | Dataset search form |
| `/search/results` | `SearchResults` | Search results list |
| `/data/:name` | `DataDetail` | Dataset detail and downloads |
| `/data/:name/viewer` | `DataViewer` | three.js 3D viewer |
| `/help/*` | `Help` | Help pages |
| `/contact` | `Contact` | Contact information |
| `*` | `CompatRedirect` | Redirects legacy `.html` and CGI URLs, otherwise renders `NotFound` |

`CompatRedirect` maps the URLs of the previous static site (for example `/Search.html`, `/Help_S1.html`,
`/DB/TE/TE0001.html`, and `/cgi-bin/SearchResult.cgi`) to their current equivalents.

### Data Model

The dataset index is bundled from `src/assets/data.json` and is keyed by dataset name. Each entry holds the
postnatal day (`pd`), `recordingVolume`, `imagingDepth`, `cellType`, `area`, `cellNum`, `expDate`, `releaseDate`,
`geneType`, and `remark` fields. `src/features/data/DataUtils.ts` exposes `exists(name)` and `search(params)`
over this index.

Per-dataset files are served statically from `public/data/`:

| File | Purpose |
| --- | --- |
| `<name>.dat` | Cell coordinate data loaded by the 3D viewer |
| `<name>.json` | Dataset metadata shown on the detail page |
| `<name>.png` | Preview image |

### Build Output

`vite.config.ts` targets `es2023` and splits vendor code into three chunks: `vendor` (React and React DOM),
`three` (three.js), and `vendor-lib` (remaining dependencies).

## Code Quality

Biome handles formatting, linting, and import sorting. The configuration uses the recommended rule preset with
the React domain enabled, single quotes, trailing commas, two-space indentation, and a line width of 120.

CSpell checks spelling across the project. Project-specific vocabulary and ignored paths are maintained in
`cspell.json`.

## Changelog

See [CHANGELOG.md](./CHANGELOG.md) for the release history.

## Learn More

- [Vite documentation](https://vite.dev/guide/)
- [React documentation](https://react.dev/)