> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solya.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture overview

> How Solya is built — the app, its operational database, and the Databricks analytics layers.

Solya is a Next.js application backed by two data stores with distinct roles.

Here's how the architecture fits together:

```mermaid theme={null}
flowchart TB
    Browser["Browser / API"]
    NextJS["Next.js app<br/>(Server Actions, Routes)"]
    Services["Services<br/>(business logic)"]
    Rules["Business rules<br/>(validation)"]
    
    PostgreSQL["PostgreSQL<br/>(operational DB)"]
    
    Databricks["Databricks<br/>(analytics)"]
    Gold["Gold layer<br/>(business-ready)"]
    Silver["Silver layer<br/>(cleaned)"]
    
    Browser --> NextJS
    NextJS --> Services
    Services --> Rules
    Services --> PostgreSQL
    Services --> Databricks
    Databricks --> Gold
    Databricks --> Silver
```

## The pieces

<CardGroup cols={3}>
  <Card title="Next.js app" icon="window">
    App Router + React Server Components. Server actions and `/api/` routes hold the
    business logic.
  </Card>

  <Card title="Operational DB" icon="database">
    PostgreSQL (Drizzle ORM) stores app-managed entities: plans, rules, alerts,
    tags, settings, audit.
  </Card>

  <Card title="Analytics (Databricks)" icon="layer-group">
    Gold/silver layers hold cleaned and business-ready retail data for analytics,
    forecasts, and decisions.
  </Card>
</CardGroup>

## Two data stores, two jobs

* **PostgreSQL (operational)** — everything users *create* in Solya: inventory plans and
  items, business rules and rulesets, alerts, tags and tagging rules, workflows, settings,
  navigation templates, and the audit trail. Org-scoped via `organizationId`.
* **Databricks (analytics)** — everything *ingested and computed*: sales, orders,
  movements, stock, dimensions, summaries, forecasts, and decision vectors. Populated by
  the data platform (ETL from POS systems) and read by the app for dashboards, KPIs,
  search, alerts, and recommendations. See [Data model](/en/developers/data-model).

## Request flow

1. A user (browser) or an integration (API token) calls a **server action** or an
   **`/api/` route**.
2. The call is authenticated and resolved to an **organization** (see
   [Authentication & multi-tenancy](/en/developers/multi-tenancy)).
3. **Services** run the business logic — reading/writing PostgreSQL and/or querying
   Databricks — and **business rules** gate mutations where applicable (see
   [Business rules engine](/en/developers/business-rules-engine)).
4. Responses use a consistent envelope with stable error codes (see
   [Error codes](/en/developers/error-codes)).

## The data platform

Heavy data work — ingestion, tag/alert evaluation, and recommendation/decision
computation — runs on the data platform (Databricks). The app triggers these as
**runs** and tracks their status and logs (ingestion runs, alert/tag evaluation runs,
workflow runs), so long-running jobs stay observable from the UI and API.