Data Layer

The data layer is the path from business data definition to server logic and screen usage. If you are building products, orders, users, reservations, or invoices, this is where the business shape becomes real application behavior.

Akan keeps this flow close to the model folder. For example, a product feature can define what a product is, how it is stored, how stock and price rules work, and how pages load product data from one module.

constant

What data exists

document

How data is stored

service

What the business does

signal

What pages can call

store

How client state is kept

How users see the data

You do not need every layer on day one. A simple read-only feature may start with constant and document, then add service or signal when the business behavior grows.

Model Shape

The constant file is the design sheet of a business object. It answers questions such as: What fields does a product have? Which values are allowed? Which fields should be shown in a lightweight list?

In the product example, the model keeps catalog information such as name, description, image URL, price, stock, and sale status. This is the shared source that the server and client can both understand.

apps/shop/lib/product/product.constant.ts

Input: Fields that can be submitted when creating or updating data.

Object: The base object shape used to build other model views.

Light: A smaller view for lists, cards, and embedded references.

Document And Service

The document file turns the model shape into stored data. It defines the database-facing model and the filter shape used when the application searches or sorts records.

apps/shop/lib/product/product.document.ts

The service file is where business behavior lives. In this simple example, the document knows how to increase its own stock, and the service decides which product should be loaded and saved.

apps/shop/lib/product/product.service.ts

Signal To UI

Signal is the layer that makes server behavior available to pages. A slice is useful when the page needs a list or dashboard view. An endpoint is useful when the page needs to run a specific action, such as adding product stock.

apps/shop/lib/product/product.signal.ts

slice: Use it for data views such as public list, admin list, dashboard, or search result.

endpoint: Use it for actions such as cancel order, approve request, send message, or complete payment.

internal: Use it for server-side jobs such as schedules, intervals, queues, or maintenance work.

Fetch And Store Instances

After signal is declared, Akan exposes app-specific client helpers from @apps/<app>/client. The two names you will see most often are fetch and st.

Use fetch when you need to call server data or pass slice metadata into Akan UI components. Use st when a client component needs to read current state or run a store action.

fetch: Generated request instance. It calls endpoints, initializes slices, loads views, and exposes fetch.slice.* metadata.

st: Generated client store instance. It provides st.use.* hooks for reading state and st.do.* actions for changing state.

Server action: call addStock with fetch

This pattern is useful when a page, action, or server-side helper needs to run a business operation. The generated fetch instance calls the server endpoint and returns the typed result.

Client zone: pass fetch.slice metadata to UI components

fetch.slice.product is not the product data itself. It is slice metadata that tells Akan UI components which model slice should be viewed, edited, refreshed, or removed.

Client form: read and change state with st

In client components, st.use.* reads the current store value and st.do.* runs the generated action. This keeps form state and business actions consistent across screens.

st is for client components. If a component uses st.use.* or st.do.*, mark it with "use client". Server pages should usually load initial data with fetch instead.

Common Decisions

When you are not sure where to put code, start with the business question. The data layer is easier to design when each file answers one kind of question.

What fields does it have?: model.constant.ts

How is it stored or searched?: model.document.ts

What business rule should run?: model.service.ts

What should a page call?: model.signal.ts

What should users see?: Model.View.tsx or Model.Zone.tsx

What state is shared on the client?: model.store.ts