> For the complete documentation index, see [llms.txt](https://stellarplan.gitbook.io/stellarplan-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stellarplan.gitbook.io/stellarplan-docs/readme.md).
# StellarPlan Web
> The StellarPlan frontend β connect Freighter, and when your salary arrives the app puts rent, bills, and savings into protected on-chain plans, leaving only what you can safely spend.
[π Documentation](https://stellarplan.gitbook.io/stellarplan-docs/)
Next.js 15 Β· Freighter wallet sign-in Β· built for the Drips Stellar Wave program (testnet)
[](https://github.com/stellarplan/stellarplan-web/actions/workflows/ci.yml)   
***
## Stack
* **Framework**: Next.js 15 (App Router, TypeScript)
* **Styling**: Tailwind CSS β custom StellarPlan skeuomorphic design system
* **Animations**: Framer Motion (< 300ms, reduced-motion friendly)
* **Icons**: Lucide React + custom emoji vault icons
* **UI**: shadcn/ui-inspired primitives
## Quick start
One command creates `.env.local`, installs dependencies, and type-checks the whole app via a build:
```bash
./scripts/setup.sh
```
Then start the dev server:
```bash
npm run dev
```
Open (the Freighter extension is required to sign in).
Manual steps (what the script automates)
```bash
cp .env.example .env.local
npm install
npm run dev
```
> The web app expects the API to be running at `NEXT_PUBLIC_API_URL` (default `http://localhost:4000/api/v1`). Edit it in `.env.local` if your API is elsewhere.
## Authentication
Sign-in is **Freighter wallet only** β no email, no password. The flow lives in [`lib/freighter.ts`](https://github.com/stellarplan/stellarplan-web/tree/main/lib/freighter.ts):
1. Connect Freighter and read the wallet address.
2. Request a challenge from the API (`POST /auth/challenge`).
3. Sign the challenge message with Freighter (SEP-53 `signMessage`).
4. Exchange the signature for JWT tokens (`POST /auth/wallet`).
The same signed-challenge pattern gates breaking a vault early. Freighter must be installed β the login screen links to it when it isn't detected.
## Architecture
```
ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ
user ββΆβ web βββββββΆβ api βββββββΆβ PostgreSQL β
β (this repo, β β (NestJS) β β β
β Next.js) β ββββββββ¬ββββββββ ββββββββββββββββ
ββββββββ¬ββββββββ β
β βΌ
β ββββββββββββββββββββββββββ
βββββββββββΆβ Stellar β
(Freighter β Horizon / Soroban RPC ββββΆ PlanVault contract
signing) ββββββββββββββββββββββββββ
```
The web app renders UI and handles Freighter signing; it calls the API for all data and business logic. The API is what talks to PostgreSQL and the PlanVault Soroban contract; the browser reaches Stellar directly only through Freighter.
## Screens
| Route | Screen |
| -------------------- | --------------------------------------- |
| `/login` / `/signup` | Freighter connect + sign-in |
| `/onboarding` | "You're connected" welcome + next step |
| `/dashboard` | Balances + vault grid + recent activity |
| `/budgets/new` | 3-step plan creation wizard |
| `/plans` | Full vault list, search & filter |
| `/plans/:id` | Vault details + break vault (signed) |
| `/activity` | Complete financial timeline |
| `/settings` | Wallet, notifications, theme, log out |
## Design system
| Token | Value | Use |
| ---------------- | --------- | ------------------------------ |
| Moon Sand | `#F2EEE8` | page background |
| Soft Ivory | `#FCFAF6` | primary surface |
| Warm Clay | `#E9DFD2` | secondary surface, dividers |
| Deep Jade | `#0F8B6D` | primary actions, success |
| Burnished Copper | `#B76E3B` | locked vaults, premium actions |
| Forest Emerald | `#2C9C69` | success status |
| Amber Gold | `#D89B2B` | warnings |
| Deep Terracotta | `#B54848` | danger |
Typography: Fraunces (headings), Manrope (UI), IBM Plex Mono (numeric). All IDs & balances are tabular-mono.
Cards use a layered shadow (`0 18px 40px` / inner highlight) with a soft bevel β subtle skeuomorphism so vaults feel tangible without looking dated.
## Folder structure
```
app/ # Next.js routes (App Router)
βββ page.tsx # welcome β dashboard redirect
βββ dashboard/
βββ budgets/new/
βββ plans/[id]/
βββ activity/
βββ settings/
βββ login|signup|onboarding|welcome/
components/
βββ plans/ # VaultCard, PlanWizard, BreakVaultModal, AllocationAnimation
βββ common/ # AppShell (auth guard), NavShell (mobile/desktop nav), NumberTicker
lib/
βββ api.ts # Typed API client with token refresh
βββ format.ts # Money, date, icon helpers
```
## CI
Every push and pull request to `main` runs the [CI workflow](https://github.com/stellarplan/stellarplan-web/tree/main/.github/workflows/ci.yml): a `build` job (`npm run build`) and a `lint` job (`npm run lint`). Use `build` and `lint` as required status checks for branch protection on `main`.
## Related repositories
* [stellarplan-api](https://github.com/stellarplan/stellarplan-api) β NestJS backend this frontend calls for all data and business logic.
* [stellarplan-contracts](https://github.com/stellarplan/stellarplan-contracts) β the PlanVault Soroban contract behind the plans.
## Maintainers
| Name | Contact |
| ---------------- | ---------------------------------------------------------------------- |
| StellarPlan Team | helloworld1-star β Telegram: @cjstixx12 β Email: |
## Contributing
Contributions are welcome β see [CONTRIBUTING.md](/stellarplan-docs/contributing.md). `main` is protected, so all changes land via pull request with CI green.
**Security:** please report vulnerabilities privately per [SECURITY.md](/stellarplan-docs/security.md).
**License:** [MIT](https://github.com/stellarplan/stellarplan-web/tree/main/LICENSE/README.md).
## Contributors
[](https://github.com/stellarplan/stellarplan-web/graphs/contributors)
---
# 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://stellarplan.gitbook.io/stellarplan-docs/readme.md?ask=&goal=
```
`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.