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**
|
## Two deliverables, one story
|
||||||
- **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
|
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
|
```sh
|
||||||
pnpm install
|
pnpm install
|
||||||
pnpm dev # vite dev server
|
pnpm dev # → http://localhost:5173
|
||||||
pnpm build # type-check + production build
|
pnpm build # type-check + production build
|
||||||
pnpm preview # serve dist/
|
|
||||||
pnpm lint
|
|
||||||
pnpm format
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
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
|
## Layout
|
||||||
|
|
||||||
```
|
```
|
||||||
src/
|
ledger/
|
||||||
├─ App.vue # router-view shell
|
├─ lantern.beancount # the mock project ledger (open in Fava)
|
||||||
├─ main.ts # plugin wiring
|
└─ run-fava.sh # launches Fava in a local venv
|
||||||
├─ style.css # tailwind + shadcn-vue CSS variables
|
src/features/deck/
|
||||||
├─ lib/utils.ts # cn() — shadcn-vue's class merger
|
├─ DeckView.vue # slide shell: nav, progress, keyboard/hash routing
|
||||||
├─ router/index.ts
|
├─ useDeck.ts # navigation composable
|
||||||
├─ stores/counter.ts # example pinia store
|
├─ data.ts # canonical figures (mirror the ledger)
|
||||||
├─ i18n/
|
├─ components/ # SlideShell, BarChart, StackedBar, AreaChart, StatCard
|
||||||
│ ├─ index.ts
|
└─ slides/ # 01-Title … 12-Fava
|
||||||
│ └─ 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)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Optional features
|
---
|
||||||
|
|
||||||
Both nostr and LNbits live as **documentation-only** folders. The deps
|
Scaffolding stack notes from the boilerplate are preserved in
|
||||||
aren't installed by default — bundle stays small for sites that don't
|
[`README.boilerplate.md`](./README.boilerplate.md).
|
||||||
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).
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue