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

# System Architecture

> High-level architecture of the Scriptonia platform.

## High-Level Architecture Diagram

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                        Frontend (Next.js Pages Router)                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐      │
│  │   Home   │→ │  Intent  │→ │ Platform │→ │ Payment  │→ │Execution │→ ...  │
│  │   (Idea) │  │   Page   │  │   Page   │  │   Page   │  │   Page   │      │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  └──────────┘      │
│       │             │             │             │             │              │
│       ↓             ↓             ↓             ↓             ↓              │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    API Routes (pages/api/)                            │   │
│  │  /idea  /intent  /platform  /payment  /execute  /dodo/*  /admin/*    │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘
                                     │
                                     ↓
┌─────────────────────────────────────────────────────────────────────────────┐
│                         Backend / Lib (lib/)                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│  │   openai.ts  │  │    x402.ts   │  │    a2a.ts    │  │   solana.ts  │    │
│  │ (OpenRouter) │  │  (Workflow)  │  │ (Agent Comms)│  │ (Payments)   │    │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                     │
│  │  platform-   │  │   prisma.ts  │  │  constants   │                     │
│  │  templates   │  │ (PostgreSQL) │  │              │                     │
│  └──────────────┘  └──────────────┘  └──────────────┘                     │
└─────────────────────────────────────────────────────────────────────────────┘
                                     │
        ┌────────────────────────────┼────────────────────────────┐
        ↓                            ↓                            ↓
┌──────────────┐            ┌──────────────┐            ┌──────────────┐
│  OpenRouter  │            │  PostgreSQL  │            │  Helius RPC  │
│  (GROK etc)  │            │  (Prisma)    │            │  / Dodo      │
└──────────────┘            └──────────────┘            └──────────────┘
```

***

## Component Overview

| Layer        | Location                                   | Role                                                                                |
| :----------- | :----------------------------------------- | :---------------------------------------------------------------------------------- |
| **Frontend** | `pages/*.tsx`, `components/`               | User flows: Idea → Intent → Platform → Payment → Execution → Completion             |
| **API**      | `pages/api/*.ts`                           | Serverless handlers; call `lib/` and persist via Prisma                             |
| **Workflow** | `lib/x402.ts`                              | Stages, `WorkflowContext`, `getWorkflowContextDB`, `updateWorkflowContextDB`        |
| **AI**       | `lib/openai.ts`                            | `processIdea`, `refineIntent`, `selectPlatform`, `executeX402Workflow` (OpenRouter) |
| **Agents**   | `lib/platform-templates.ts`, `lib/x402.ts` | `getAgentForFile`, `AGENT_ROLES`, `generatePlatformDeliverables`                    |
| **A2A**      | `lib/a2a.ts`                               | Agent-to-Agent message bus, `sendA2ARequest`, `shareA2AData`                        |
| **Payments** | `lib/solana.ts`, `api/dodo/*`              | Solana validation, Dodo checkout, webhooks                                          |
| **Data**     | `lib/prisma.ts`, `prisma/schema.prisma`    | `Workflow`, `User`, `Transaction`, `AgentStat`, `ZipFile`, etc.                     |

***

## Technology Stack

| Area          | Technologies                                       |
| :------------ | :------------------------------------------------- |
| **Runtime**   | Node.js 18+                                        |
| **Framework** | Next.js 14 (Pages Router)                          |
| **Language**  | TypeScript                                         |
| **AI**        | OpenRouter (GROK-4, Qwen 3, Gemini 2.5)            |
| **Database**  | PostgreSQL, Prisma ORM                             |
| **Payments**  | Solana (Helius RPC, \$SCRIPT/SPL), Dodo (card/UPI) |
| **Frontend**  | React 18, Tailwind CSS, Reown AppKit / Phantom     |

***

## Design Decisions

1. **Pages Router** — API and pages use `pages/`; App Router is not used for core workflow.
2. **Workflow state** — Prefer `getWorkflowContextDB` / `updateWorkflowContextDB`; in-memory in `x402` is fallback when DB is unavailable.
3. **AI provider** — OpenRouter for multi-model support; `DEFAULT_MODEL` and `OPENROUTER_API_KEY_*` select provider.
4. **Unified pricing** — `UNIFIED_PRICE_SCRIPT` / `UNIFIED_PRICE_USD`; platform choice does not change payment amount.
5. **Execution** — `generatePlatformDeliverables` in `platform-templates` runs agents in parallel by file assignment; `getAgentForFile` maps paths to ProductManager, FrontendDev, BackendDev, DevOpsEngineer, ToolManager.
6. **Admin APIs** — No built-in auth in handlers; in production they should be protected (e.g. API key, role-based auth).