> For the complete documentation index, see [llms.txt](https://anthonyyoo.gitbook.io/atlas-grid/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://anthonyyoo.gitbook.io/atlas-grid/frontend-architecture.md).

# Frontend Architecture

## Repository structure

```
src/
├── app/                         # Routes and API endpoints
├── scenes/
│   └── graph-workspace/         # The complete AtlasGrid workspace
├── features/
│   ├── app-selection/           # Choosing an app
│   └── graph-search/            # Finding screens and transitions
├── modules/
│   └── graph/
│       ├── core/                # Pure graph rules and calculations
│       ├── contracts/           # Validated data shapes
│       └── adapters/
│           ├── data/            # Queries and browser-local layouts
│           ├── react-flow/      # Graph rendering and interaction
│           └── layout/          # Offline layout generation
├── server/
│   ├── db/                      # Database connection
│   ├── repositories/            # PostgreSQL queries
│   └── services/                # Server use cases
├── shared/                      # Reusable UI and setup
└── test/                        # Shared test utilities
```

Each folder has one clear responsibility:

* **`app/`** chooses which experience appears at a URL and exposes API routes.
* **`scenes/`** combines several capabilities into a complete page.
* **`features/`** contains actions a user recognizes, such as selecting an app or searching the graph.
* **`modules/graph/`** owns graph meaning, validation, calculations, rendering adapters, and authoring tools.
* **`server/`** keeps database access and server-only logic out of the browser.
* **`shared/`** contains reusable code that is not specific to one AtlasGrid feature.

## Why it is organized this way

AtlasGrid combines a large interactive canvas, graph calculations, browser state, API data, and database access. Separating those responsibilities keeps a change in one area from spreading through the entire application.

The graph's core rules are plain TypeScript and do not depend on React, Next.js, Zustand, TanStack Query, or React Flow. Adapters connect those rules to specific tools. This lets the browser, server, tests, and authoring scripts reuse the same graph behavior without duplicating it.

Scenes coordinate features, while features remain independent. Routes stay small, and server code remains isolated from browser code. This makes ownership clear and reduces accidental coupling.

## Import and export rules

The graph module exposes three approved entry points:

| Import                   | Where it can be used        | Purpose                                        |
| ------------------------ | --------------------------- | ---------------------------------------------- |
| `@/modules/graph`        | Browser, server, and tests  | Graph models, contracts, and pure rules        |
| `@/modules/graph/client` | Browser only                | Queries, browser-local layouts, and React Flow |
| `@/modules/graph/layout` | Node authoring scripts only | Layout generation and static previews          |

The main rules are:

* Code outside the graph module must use these public entry points instead of importing internal files directly.
* Internal graph files use relative imports.
* Graph core can import only graph core and cannot import framework packages.
* Graph adapters can depend on contracts, core, shared code, and their own adapter—not on other adapters.
* Features cannot import routes, scenes, server code, or another feature's internal files.
* Shared code can import only shared code.
* Browser code cannot import `server/`, and server code cannot import the browser graph entry point.

These rules keep dependencies flowing toward stable, reusable code instead of back toward pages and interface components.

## Check that maintain the structure

* `npm run lint:boundaries` scans imports and fails when a dependency crosses an architectural boundary.

## How it scales

A new user capability can be added as a feature and composed by a scene. New graph behavior can be added to core without rewriting the interface. A new external tool can be introduced through an adapter without changing the graph's meaning.

This structure also supports larger graphs because expensive graph rules, rendering work, and data access remain separate. Each layer can be tested, profiled, or optimized without replacing the others.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://anthonyyoo.gitbook.io/atlas-grid/frontend-architecture.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.