A real specification, start to finish — read it before you sign up

# Complete Specification: Ledgerly

> This document is an exhaustive specification for building the **Ledgerly** project.
> Read it entirely before you start coding. Follow every single point.
> Make NO assumptions — anything not mentioned here should NOT be implemented.

## 1. Project Overview

- **Name**: Ledgerly
- **Description**: A simple invoicing and expense tracker for freelancers who bill in multiple currencies and hate spreadsheets.
- **Target audience**: Freelancers, contractors and one-person studios billing international clients
- **Primary goal**: Sell a recurring subscription
- **Languages**: en, fr
- **i18n**: Implement a complete translation system. All strings must be in translation files, never hardcoded.

## 2. Tech Stack

### Framework & Runtime
- **Framework**: Next.js (App Router, latest stable version)
- **Language**: TypeScript (strict mode)
- **Runtime**: Node.js
- **ORM**: Prisma
- **UI**: Tailwind CSS
- **Components**: shadcn/ui

### Database
- **DB**: postgres
- Use migrations for schema management
- Always use prepared statements (no variable interpolation in SQL)

### Hosting
- **Target**: vercel

## 3. Database Schema

### Table `users`
| Column | Type | Description |
|--------|------|-------------|
| id | INT PK AUTO | Unique identifier |
| email | VARCHAR(255) UNIQUE | Login email |
| password_hash | VARCHAR(255) | Hashed password (bcrypt) |
| first_name | VARCHAR(100) | First name |
| last_name | VARCHAR(100) | Last name |
| role | ENUM | User role |
| created_at | DATETIME | Creation date |
| updated_at | DATETIME | Last modified |

### Business-specific entities
Create tables for the following entities (with appropriate relationships):
Client, Invoice, LineItem, Expense, Receipt, PaymentReminder, Report

For each entity:
- Add `id`, `created_at`, `updated_at`
- Add appropriate foreign keys
- Add indexes on frequently queried columns

### Table `subscriptions`
| Column | Type | Description |
|--------|------|-------------|
| id | INT PK | Identifier |
| user_id | FK -> users | User |
| plan | VARCHAR | Subscribed plan |
| status | ENUM | active, canceled, expired |
| stripe_subscription_id | VARCHAR | Stripe ID |
| current_period_end | DATETIME | Period end |
| created_at | DATETIME | Date |

## 4. Authentication

- **Method**: all
- **Provider**: nextauth

### Authentication Flows

#### Sign Up
1. User enters email + password (or clicks Google/GitHub)
2. Server-side validation: valid email, password >= 8 characters
3. Password hashing (bcrypt, cost 12)
4. Account creation in database
5. Automatic login (session regenerated)
6. Welcome email
7. Redirect to dashboard

#### Login
1. Email + password
2. Bcrypt verification
3. Session regeneration (prevents session fixation)
4. Redirect to requested page (or dashboard by default)

#### Forgot Password
1. User enters their email
2. Generate a random token (64 chars, crypto-safe)
3. Store token + expiration (1 hour)
4. Send email with reset link
5. Always display the same message (security: do not reveal whether the email exists)
6. Reset page: new password + confirmation
7. Invalidate token after use

#### Logout
1. Destroy the session
2. Delete the cookie
3. Redirect to homepage

#### OAuth (Google/GitHub)
1. Redirect to provider
2. Callback with authorization code
3. Exchange for access token
4. Retrieve user information
5. Create or log in to account
6. Session + redirect

## 5. SaaS Features

### Product Core
Create a branded invoice in under 60 seconds and get paid via a hosted payment link.

### User Actions
Create invoices, log expenses, attach receipts, send payment reminders, export accountant-ready reports.

### Business Entities
Client, Invoice, LineItem, Expense, Receipt, PaymentReminder, Report

### Business Model: free_trial

#### Pricing Plans
Solo — 5 clients, 20 invoices/month
Studio — unlimited clients, recurring invoices, reminders
Agency — multi-seat, roles, API access

#### Expiration Behavior
When the subscription expires, the user switches to read-only mode. They can view their data but can no longer create/modify.

### Payment
- **Provider**: stripe
- Implement webhooks to handle: successful payment, failed payment, subscription canceled, renewal
- Handle error cases (expired card, insufficient funds)
- Store Stripe/provider IDs in database (customer_id, subscription_id)
- **Free trial**: 14 days

### User Dashboard
Metrics to display:
Outstanding balance, paid this month, overdue invoices, revenue by currency

### Admin Panel
Accessible only to users with the `admin` role.
Features:
- User management (list, details, ban, plan modification)
- Payment and revenue tracking (MRR, churn, lifetime value)
- Usage statistics and business metrics
- Support ticket system

### Multi-user / Teams
Roles: Owner (billing + members), Member (create/send invoices), Viewer (read-only reports)
- Email invitation system
- Each member inherits their role's permissions
- The team owner cannot be removed

### Public API
- RESTful API with API key authentication
- Auto-generated documentation
- Rate limiting per API key
- Versioning (v1/)

### Third-party Integrations
Implement the following integrations:
- Stripe
- Email_service
- Google

### Onboarding
Step-by-step wizard for new users:
1. Welcome + quick overview
2. Initial setup (basic information)
3. First key action (create first object)
4. Confirmation + dashboard access
- Option to skip
- Progress indicator

### Data Export
Supported formats: CSV, PDF

### Real-time
Real-time features (WebSocket or SSE):
- notifications
- live_updates

## 6. Site Pages

### Required Pages
- `/ (Home)`
- `/login`
- `/register`
- `/forgot-password`
- `/dashboard`
- `/dashboard/account`
- `/pricing`
- `/blog`
- `/blog/[slug]`
- `/legal-notice`
- `/terms-of-service`
- `/privacy-policy`
- `(cookie banner, no dedicated page)`

### For Each Page
- Unique and descriptive title (< 60 characters)
- Unique meta description (< 160 characters)
- Unique H1
- Breadcrumb (except homepage)
- Loading state for asynchronous data
- Custom 404 page

## 7. Design & UX

### Visual Style: modern minimal
### Primary Color: #4f46e5

### Design System
- Define CSS variables for: colors (primary, secondary, gray scale, success, error, warning), sizes (spacing scale), typography (font sizes, weights, line heights), border-radius, shadows
- Use these variables everywhere (never hardcoded values)
- Reusable components: Button, Input, Card, Modal, Toast, Badge, Avatar, Dropdown, Table

### Typography
- Primary font: Inter or system font stack
- Clear hierarchy: H1 (2.5rem), H2 (2rem), H3 (1.5rem), body (1rem), small (0.875rem)
- Line-height: 1.5 for body, 1.2 for headings

### Responsive: mobile_first
- Breakpoints: mobile (< 768px), tablet (768-1024px), desktop (> 1024px)
- Mobile navigation: hamburger menu with drawer
- No horizontal scrolling
- Touch-friendly: buttons min 44x44px
- Responsive images (srcset or next/image)

### Dark Mode: Light/dark toggle. Store preference in localStorage. Visible toggle button in header.

### Animations
- Subtle hover transitions (scale, opacity, color) - duration: 200ms
- Element reveal on scroll (fade-in + slide-up) - IntersectionObserver
- Respect `prefers-reduced-motion`: disable all animations if active

### Accessibility (minimum)
- Sufficient contrast (WCAG AA minimum)
- Keyboard navigation (visible focus)
- Alt text on all images
- Labels on all inputs
- ARIA roles on custom components (modal, dropdown, tabs)
- Skip to content link

## 8. SEO & Performance

### Level: advanced

### On-page SEO (all pages)
- Unique `<title>` (< 60 chars) with primary keyword
- Unique `<meta description>` (< 160 chars) with call-to-action
- Single `<h1>` per page
- Semantic structure: header, main, nav, footer, article, section
- Clean and descriptive URLs (no /page?id=123)
- Canonical tags

### Technical SEO
- **XML Sitemap**: dynamically generated, includes all indexable pages
- **robots.txt**: block admin/dashboard pages
- **Schema.org**: Organization, WebSite, BreadcrumbList (+ specific type based on content)
- **OpenGraph**: og:title, og:description, og:image, og:type for each page
- **Twitter Card**: twitter:card, twitter:title, twitter:description, twitter:image
- **Internal links**: each page should have at least 2-3 internal links
- **Breadcrumbs**: with schema.org BreadcrumbList

### Target Keywords
freelance invoicing, expense tracker, multi-currency invoices
- Integrate these keywords naturally into H1, H2, meta, and content
- Create dedicated pages for the most important keywords

### Performance
- Lighthouse score > 90 (Performance, Accessibility, Best Practices, SEO)
- Images: WebP/AVIF format, lazy loading, explicit dimensions
- CSS: critical inline, rest deferred
- JS: defer/async, code splitting if JS framework
- Fonts: preload, font-display: swap
- Compression: gzip/brotli
- Cache: appropriate Cache-Control headers

### Analytics: plausible

## 9. Security

### Mandatory (non-negotiable)
- **HTTPS**: enforce HTTPS everywhere (301 redirect)
- **Passwords**: bcrypt (cost >= 12), NEVER in plaintext, NEVER MD5/SHA
- **SQL**: prepared statements exclusively, no interpolation
- **XSS**: escape all HTML output (htmlspecialchars)
- **CSRF**: token on all POST forms
- **Headers**: X-Content-Type-Options, X-Frame-Options, Strict-Transport-Security
- **Cookies**: HttpOnly, Secure, SameSite=Lax
- **Sessions**: regenerate ID after login (session fixation prevention)
- **Uploads**: validate MIME type, limit size, rename files
- **Errors**: never expose stack traces in production

### Additional Measures
- **Rate limiting**: 60 req/min per IP on APIs, 5 login attempts per 15 min
- **Content Security Policy**: define a strict CSP

## 10. Legal & GDPR

### Required Legal Pages
- Legal notice (publisher, host, publication director)
- Terms of Service / Terms and Conditions
- Privacy policy (data collection, processing, rights)
- Cookie banner with granular consent

### GDPR Compliance
- Explicit consent before any data collection
- Cookie banner with granular choices (necessary, analytics, marketing)
- Right of access: user can download all their data (JSON export)
- Right to erasure: user can delete their account and all their data
- Right to rectification: user can modify their information
- Record of processing activities (internal documentation)
- No tracking before consent
- Data retention: define a duration and automatically delete

## 11. Deployment

### Configuration
- Environment variables for ALL keys/secrets (never in code)
- `.env.example` file with all required variables (without sensitive values)
- `.gitignore`: .env, node_modules, vendor, uploads, .DS_Store

### CI/CD
- Automated build + tests on each push
- Automatic deploy on main branch
- Preview deployments on PRs (if Vercel/Netlify)

## 12. Suggested File Structure

```
src/
  app/
    layout.tsx              # Main layout
    page.tsx                # Home page
    globals.css             # Global styles
    (auth)/
      login/page.tsx
      register/page.tsx
    dashboard/
      layout.tsx
      page.tsx
    api/
      auth/[...]/route.ts
      webhooks/stripe/route.ts
  components/
    ui/                     # shadcn/ui components
    layout/                 # Header, Footer, Sidebar
    forms/                  # Form components
  lib/
    db.ts                   # Prisma client
    auth.ts                 # Authentication helpers
    stripe.ts               # Stripe client
    utils.ts                # Utilities
  types/
    index.ts                # TypeScript types
prisma/
  schema.prisma
public/
  images/
.env.example
```

## 13. Development Rules

### Code Quality
- No dead or commented-out code
- Clear and descriptive naming (no variables like a, b, x)
- Short functions (< 50 lines ideally)
- DRY: refactor duplicated code
- One file = one responsibility

### Naming Conventions
- Components: PascalCase (UserCard.tsx)
- Functions/variables: camelCase
- Constants: UPPER_SNAKE_CASE
- CSS files: kebab-case
- API routes: kebab-case (/api/create-checkout)

### Git
- Atomic commits (one feature = one commit)
- Descriptive commit messages in English
- Branches: feature/xxx, fix/xxx, hotfix/xxx

### STRICT RULES — What Must NEVER Be Done
- Never put secrets in code (API keys, passwords)
- Never leave `console.log` or `var_dump` in production
- Never use `SELECT *` without LIMIT
- Never use inline CSS except in exceptional cases
- Never use eval() or unsanitized dynamic code
- Never use an external library if a native solution exists in < 20 lines