docs: rewrite README for the presentation
Document the two deliverables (deck + ledger), how to run each, and the headline figures. Original boilerplate stack notes preserved in README.boilerplate.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Patrick Mulligan
parent
da0161963a
commit
b7d8a94e97
2 changed files with 112 additions and 53 deletions
48
README.boilerplate.md
Normal file
48
README.boilerplate.md
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
# boilerplate-website
|
||||
|
||||
Opinionated Vue 3 starter — the base every new aiolabs website forks from.
|
||||
(This project — the accounting pitch deck — was forked from it; see the main
|
||||
[`README.md`](./README.md).)
|
||||
|
||||
## Stack
|
||||
|
||||
- **Vue 3.5** + **Vite 8** + **TypeScript 6**
|
||||
- **shadcn-vue** (via `reka-ui` + `class-variance-authority` + `tailwind-merge`) — components.json pre-wired, run `pnpm dlx shadcn-vue@latest add <name>` to copy components in
|
||||
- **Tailwind CSS 4** (via `@tailwindcss/vite` — no `tailwind.config.js`)
|
||||
- **Pinia 3** — sample `useCounterStore` in `src/stores/`
|
||||
- **Vue Router 5** — file in `src/router/index.ts`, lazy-loaded views in `src/views/`
|
||||
- **Vue I18n 11** — `src/i18n/locales/{en,es}.json`
|
||||
- **vee-validate 4** + **zod 3** — form validation primitives (zod pinned to ^3 until `@vee-validate/zod` ships a v4-compatible resolver)
|
||||
- **@lucide/vue** — icon set (`lucide-vue-next` is deprecated upstream)
|
||||
- **ESLint 10** (flat config) + **Prettier 3**
|
||||
|
||||
## Quick start
|
||||
|
||||
```sh
|
||||
pnpm install
|
||||
pnpm dev # vite dev server
|
||||
pnpm build # type-check + production build
|
||||
pnpm preview # serve dist/
|
||||
pnpm lint
|
||||
pnpm format
|
||||
```
|
||||
|
||||
## Optional features
|
||||
|
||||
Both nostr and LNbits live as **documentation-only** folders under
|
||||
`src/features/`. The deps aren't installed by default — bundle stays small for
|
||||
sites that don't need them. Each folder's README walks you through enabling.
|
||||
|
||||
- **`src/features/nostr/`** — connect to relays, sign/publish events, contact forms that DM the site owner's npub
|
||||
- **`src/features/lnbits/`** — create invoices, accept Lightning payments via an LNbits instance
|
||||
|
||||
## Pulling boilerplate dep refreshes into a forked site
|
||||
|
||||
```sh
|
||||
git remote add boilerplate forgejo@git.atitlan.io:aiolabs/boilerplate-website.git
|
||||
git fetch boilerplate
|
||||
git merge boilerplate/main
|
||||
```
|
||||
|
||||
When a site diverges enough to no longer benefit from these merges, drop the
|
||||
remote — it becomes its own thing.
|
||||
129
README.md
129
README.md
|
|
@ -1,74 +1,85 @@
|
|||
# boilerplate-website
|
||||
# Accounting for the Collective — pitch deck
|
||||
|
||||
Opinionated Vue 3 starter — the base every new aiolabs website forks from.
|
||||
A slide presentation that pitches an incubator collective on adopting real
|
||||
accounting practices, plus the **Beancount ledger** that backs every number in
|
||||
it. Built on the aiolabs `boilerplate-website` (Vue 3 + Vite + Tailwind 4).
|
||||
|
||||
## Stack
|
||||
Presented by the accounting team: **Pat** (software) and **Rayan** (accountant).
|
||||
|
||||
- **Vue 3.5** + **Vite 8** + **TypeScript 6**
|
||||
- **shadcn-vue** (via `reka-ui` + `class-variance-authority` + `tailwind-merge`) — components.json pre-wired, run `pnpm dlx shadcn-vue@latest add <name>` to copy components in
|
||||
- **Tailwind CSS 4** (via `@tailwindcss/vite` — no `tailwind.config.js`)
|
||||
- **Pinia 3** — sample `useCounterStore` in `src/stores/`
|
||||
- **Vue Router 5** — file in `src/router/index.ts`, lazy-loaded views in `src/views/`
|
||||
- **Vue I18n 11** — `src/i18n/locales/{en,es}.json`
|
||||
- **vee-validate 4** + **zod 3** — form validation primitives (zod pinned to ^3 until `@vee-validate/zod` ships a v4-compatible resolver)
|
||||
- **@lucide/vue** — icon set (`lucide-vue-next` is deprecated upstream)
|
||||
- **ESLint 10** (flat config) + **Prettier 3**
|
||||
## Two deliverables, one story
|
||||
|
||||
## Quick start
|
||||
Both tell the story of **Project Lantern** — a mock hardware project inside the
|
||||
collective — over its first seven months (Jan–Jul 2026).
|
||||
|
||||
1. **The deck** (`src/features/deck/`) — a full-screen slide presentation with
|
||||
simplified visualizations: budget allocation, cash-over-time, the
|
||||
double-entry behind a $5,000 server purchase, who holds a balance with the
|
||||
collective, and a live balance sheet.
|
||||
2. **The ledger** (`ledger/lantern.beancount`) — the same story as a real
|
||||
plain-text ledger you open in **Fava** to show the actual reporting software
|
||||
behind the pitch. The deck's figures are pulled straight from it (see
|
||||
`src/features/deck/data.ts`), so the two always agree.
|
||||
|
||||
## Run the deck
|
||||
|
||||
```sh
|
||||
pnpm install
|
||||
pnpm dev # vite dev server
|
||||
pnpm build # type-check + production build
|
||||
pnpm preview # serve dist/
|
||||
pnpm lint
|
||||
pnpm format
|
||||
pnpm dev # → http://localhost:5173
|
||||
pnpm build # type-check + production build
|
||||
```
|
||||
|
||||
Navigate with **← / →** (or space), **Home/End** to jump, click the dots, or
|
||||
deep-link a slide with a hash (e.g. `/#7`).
|
||||
|
||||
## Run the reporting (Fava)
|
||||
|
||||
The system Fava package is missing its `beanquery` dependency, so a helper
|
||||
script spins up a local venv (reusing system packages) the first time:
|
||||
|
||||
```sh
|
||||
./ledger/run-fava.sh # → http://localhost:5001
|
||||
# or choose a port: ./ledger/run-fava.sh 5005
|
||||
```
|
||||
|
||||
Validate the ledger directly with Beancount:
|
||||
|
||||
```sh
|
||||
bean-check ledger/lantern.beancount # should print nothing = valid
|
||||
```
|
||||
|
||||
In Fava, the interesting views are **Balance Sheet**, **Income Statement**,
|
||||
**Budget** (the plan the seed round was raised against), the **Journal**, and
|
||||
**Events** (project milestones).
|
||||
|
||||
## The numbers (as of 2026-07-30)
|
||||
|
||||
| | |
|
||||
|---|---:|
|
||||
| Seed round raised | $100,000 |
|
||||
| Net worth today (total assets) | $48,885 |
|
||||
| — Bank + petty cash | $43,885 |
|
||||
| — Equipment (servers, capitalized) | $5,000 |
|
||||
| Revenue to date (pre-orders) | $6,500 |
|
||||
| Expenses to date | $60,615 |
|
||||
|
||||
Assets ($48,885) = Liabilities ($0) + Equity ($48,885). The books balance —
|
||||
verified against Fava and `bean-check`.
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
src/
|
||||
├─ App.vue # router-view shell
|
||||
├─ main.ts # plugin wiring
|
||||
├─ style.css # tailwind + shadcn-vue CSS variables
|
||||
├─ lib/utils.ts # cn() — shadcn-vue's class merger
|
||||
├─ router/index.ts
|
||||
├─ stores/counter.ts # example pinia store
|
||||
├─ i18n/
|
||||
│ ├─ index.ts
|
||||
│ └─ locales/{en,es}.json
|
||||
├─ views/HomeView.vue # proof-of-wiring page (i18n + pinia + tailwind)
|
||||
└─ features/
|
||||
├─ nostr/README.md # opt-in: nostr-tools wiring (see file)
|
||||
└─ lnbits/README.md # opt-in: LNbits payments wiring (see file)
|
||||
ledger/
|
||||
├─ lantern.beancount # the mock project ledger (open in Fava)
|
||||
└─ run-fava.sh # launches Fava in a local venv
|
||||
src/features/deck/
|
||||
├─ DeckView.vue # slide shell: nav, progress, keyboard/hash routing
|
||||
├─ useDeck.ts # navigation composable
|
||||
├─ data.ts # canonical figures (mirror the ledger)
|
||||
├─ components/ # SlideShell, BarChart, StackedBar, AreaChart, StatCard
|
||||
└─ slides/ # 01-Title … 12-Fava
|
||||
```
|
||||
|
||||
## Optional features
|
||||
---
|
||||
|
||||
Both nostr and LNbits live as **documentation-only** folders. The deps
|
||||
aren't installed by default — bundle stays small for sites that don't
|
||||
need them. Each folder's README walks you through enabling.
|
||||
|
||||
- **`src/features/nostr/`** — connect to relays, sign/publish events, contact forms that DM the site owner's npub
|
||||
- **`src/features/lnbits/`** — create invoices, accept Lightning payments via an LNbits instance
|
||||
|
||||
## Versioning strategy
|
||||
|
||||
The boilerplate's `main` branch is **the "tools wired, no content" baseline**. New site = clone (or fork on Forgejo) → start adding content immediately.
|
||||
|
||||
To pull dep refreshes from the boilerplate into an existing site:
|
||||
|
||||
```sh
|
||||
git remote add boilerplate forgejo@git.atitlan.io:aiolabs/boilerplate-website.git
|
||||
git fetch boilerplate
|
||||
git merge boilerplate/main
|
||||
```
|
||||
|
||||
When a site diverges enough to no longer benefit from these merges, drop the remote — it becomes its own thing.
|
||||
|
||||
## Keeping deps current
|
||||
|
||||
- The boilerplate gets dep bumps via PRs (Renovate / Dependabot configurable; otherwise periodic `pnpm update --latest` + manual review).
|
||||
- The Vue ecosystem (vue, pinia, router, i18n, vee-validate) versions in lockstep — when one majors, the others usually follow within weeks.
|
||||
- Tailwind 4 + shadcn-vue + reka-ui is the current modern combo. shadcn-vue uses tw-animate-css (not the deprecated tailwindcss-animate plugin).
|
||||
Scaffolding stack notes from the boilerplate are preserved in
|
||||
[`README.boilerplate.md`](./README.boilerplate.md).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue