first commit

README.md

@@ -1,36 +1,103 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# App Spese
 
-## Getting Started
+Full-stack personal finance app built with Next.js App Router, TypeScript,
+Tailwind CSS, and PostgreSQL.
 
-First, run the development server:
+The browser only talks to Next.js Route Handlers. PostgreSQL credentials and
+session tokens stay on the server.
+
+## Docker Compose
+
+Copy the example environment file and choose a strong database password:
 
 ```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
+cp .env.example .env
+docker compose up --build -d
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+The first startup initializes the PostgreSQL schema from `database/init.sql`.
+Open `http://localhost:3000`: the app redirects to `/setup` and asks you to
+create the first account. The setup page becomes unavailable as soon as that
+account exists.
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+## Local Development
 
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+Start PostgreSQL with Docker:
 
-## Learn More
+```bash
+docker compose up -d postgres
+```
 
-To learn more about Next.js, take a look at the following resources:
+The compose file publishes PostgreSQL on `localhost:5432` by default so the
+local Next.js development server can reach it.
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+Create `.env.local`:
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+```env
+DATABASE_URL=postgresql://appspese:change-me@localhost:5432/appspese
+```
 
-## Deploy on Vercel
+Install dependencies and run Next.js:
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+```bash
+pnpm install
+pnpm dev
+```
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+## Data Model
+
+Tables:
+
+- `users` and `sessions`: local credentials and revocable login sessions.
+- `subscriptions`: recurring payment rules.
+- `subscription_payments`: paid or unpaid state for generated renewals.
+- `bills`: expected manual bills with due dates.
+- `one_time_payments`: immediate manual outgoing payments.
+- `payments_ledger`: single source of truth for real paid outgoing money.
+- `payment_titles`: reusable deduplicated payment names.
+- `income`: incoming money.
+- `user_settings`: one row of preferences per user.
+
+Subscriptions and bills count as projected obligations until paid. Paid
+outgoing money is written to `payments_ledger`, with unique database constraints
+preventing duplicate ledger rows.
+
+Subscriptions keep service activation and billing separate. Recurring payments
+start from the first payment date, can stop at an optional end date or after an
+optional number of installments, and may otherwise continue indefinitely.
+Suspended and terminated subscriptions do not generate new virtual renewals,
+while already recorded payments remain available as history.
+Custom renewal intervals use an exact quantity and unit, supporting schedules
+such as every two weeks, every three months, or every two years.
+
+## Database Migrations
+
+`database/init.sql` contains the complete schema for new installations.
+Versioned files in `database/migrations` update existing volumes. After pulling
+an update that includes a new migration, apply it once with:
+
+```bash
+cat database/migrations/001_subscription_lifecycle.sql | docker compose exec -T postgres psql -v ON_ERROR_STOP=1 -U appspese -d appspese
+cat database/migrations/002_subscription_custom_intervals.sql | docker compose exec -T postgres psql -v ON_ERROR_STOP=1 -U appspese -d appspese
+```
+
+## Authentication
+
+There is no public registration page. The `/setup` page and its API endpoint are
+available only while the database contains no users. The first request that
+creates an account takes a PostgreSQL transaction lock, preventing concurrent
+requests from creating multiple initial accounts.
+
+- Passwords are hashed with bcrypt.
+- Login sessions use random secrets stored in an HTTP-only cookie.
+- Only a SHA-256 hash of each session secret is stored in PostgreSQL.
+- API Route Handlers verify the current user server-side and ignore
+  client-provided user identifiers.
+
+## Verification
+
+```bash
+pnpm lint
+pnpm build
+docker compose config
+```