# Pages & Routing

# Bilko Frontend Pages

**Framework:** Next.js 15 (App Router)
**Current State:** Fully implemented with mock data
**Future State:** Will require API integration to replace mock data

---

## Route Architecture Overview

```mermaid
graph TD
    ROOT["app/layout.tsx\n(Root HTML, Inter font, metadata)"]

    ROOT --> LANDING["/ — Landing Page\napp/page.tsx"]
    ROOT --> AUTH["(auth) group\nNo shared layout"]
    ROOT --> DASH["(dashboard) group\napp/(dashboard)/layout.tsx\nSidebar + TopBar"]

    AUTH --> LOGIN["/login\nLoginPage"]
    AUTH --> REGISTER["/register\nRegisterPage"]

    DASH --> DASHBOARD["/dashboard\nDashboard Home"]
    DASH --> INVOICES["/invoices\nInvoice List"]
    DASH --> INV_NEW["/invoices/new\nInvoice Wizard"]
    DASH --> EXPENSES["/expenses\nExpense List"]
    DASH --> EXPENSES_NEW["/expenses/new\nAdd Expense"]
    DASH --> PURCHASES["/purchases\nPurchases (alias → expenses)"]
    DASH --> BANKING["/banking\nBanking Hub"]
    DASH --> REPORTS["/reports\nReports Hub"]
    DASH --> REPORTS_PL["/reports/profit-loss\nP&L Report"]
    DASH --> REPORTS_VAT["/reports/vat\nVAT Report"]
    DASH --> SETTINGS["/settings\nSettings"]

    LANDING --> LOGIN
    LOGIN --> DASHBOARD
    REGISTER --> DASHBOARD

    classDef layout fill:#1e1e2e,color:#cdd6f4,stroke:#89b4fa
    classDef auth fill:#313244,color:#cba6f7,stroke:#cba6f7
    classDef dashboard fill:#1e1e2e,color:#a6e3a1,stroke:#a6e3a1
    classDef reports fill:#313244,color:#89dceb,stroke:#89dceb
    class ROOT,DASH layout
    class AUTH,LOGIN,REGISTER auth
    class DASHBOARD,INVOICES,INV_NEW,EXPENSES,EXPENSES_NEW,PURCHASES,BANKING,SETTINGS dashboard
    class REPORTS,REPORTS_PL,REPORTS_VAT reports
```

---

## Layouts

### Root Layout
- **Route:** `/`
- **File:** `app/layout.tsx`
- **Purpose:** Root HTML wrapper, applies Inter font, sets metadata
- **Metadata:**
  - Title: "Bilko - Accounting Made Simple"
  - Description: "Modern accounting software for Balkan businesses"
- **Dependencies:** Inter font from Google Fonts
- **Current State:** Fully implemented

### Dashboard Layout
- **Route:** `/(dashboard)/*`
- **File:** `app/(dashboard)/layout.tsx`
- **Purpose:** Layout wrapper for all authenticated pages
- **Key Components:**
  - Sidebar (desktop persistent, mobile overlay)
  - TopBar (header with search, notifications, user menu)
- **State Management:** Local state for mobile sidebar toggle
- **Mobile Responsiveness:** Responsive sidebar with overlay
- **Current State:** Fully implemented

```mermaid
graph LR
    DL["DashboardLayout\napp/(dashboard)/layout.tsx"]

    DL --> SB["Sidebar\ncomponents/sidebar.tsx\n• Logo\n• Main nav (5 items)\n• Bottom nav (Settings)\n• Active state via usePathname"]
    DL --> TB["TopBar\ncomponents/top-bar.tsx\n• Mobile menu button\n• Search (Cmd+K)\n• Notifications bell\n• User dropdown menu"]
    DL --> SLOT["Page Slot\n{children}"]

    SB -->|"dark sidebar #111113"| SCREEN["Rendered Screen"]
    TB -->|"white top bar"| SCREEN
    SLOT -->|"light content #FAFAFA"| SCREEN
```

---

## Pages

### Dashboard (Home)
- **Route:** `/dashboard`
- **File:** `app/(dashboard)/dashboard/page.tsx`
- **Purpose:** Financial overview and quick actions
- **Key Components:**
  - Metric cards (Cash Balance, Revenue MTD, Unpaid Invoices)
  - P&L Bar Chart (6-month trend)
  - Receivables Aging (stacked bar chart)
  - Expenses by Category (donut chart)
  - Recent Transactions table
  - Quick Actions card
- **Data Requirements (Future API):**
  - `GET /api/metrics` — cashBalance, revenueMTD, unpaidInvoices, expensesMTD, profitMTD, cashFlowChange
  - `GET /api/pl/monthly` — monthly P&L data (revenue, expenses, profit)
  - `GET /api/receivables/aging` — receivables breakdown (current, 30d, 60d, 90d+)
  - `GET /api/expenses/by-category` — expenses grouped by category
  - `GET /api/transactions/recent?limit=5` — recent transactions
- **Charts:** Recharts (BarChart, PieChart) with responsive containers
- **Current State:** Mock data from `lib/mock-data.ts`
- **Mobile Responsive:** Grid adapts 1/2/3 columns based on breakpoint

```mermaid
graph TD
    DP["Dashboard Page\n/dashboard"]

    DP --> ROW1["Row 1 — Metric Cards\ngrid-cols-1 md:grid-cols-3"]
    DP --> ROW2["Row 2 — Charts\ngrid-cols-1 md:grid-cols-3"]
    DP --> ROW3["Row 3 — Tables + Actions\ngrid-cols-1 lg:grid-cols-3"]

    ROW1 --> MC1["Cash Balance\nwith trend arrow"]
    ROW1 --> MC2["Revenue MTD\ncurrent month total"]
    ROW1 --> MC3["Unpaid Invoices\nwith warning badge"]

    ROW2 --> CH1["P&L Bar Chart\nRecharts BarChart\n6-month revenue/expenses/profit"]
    ROW2 --> CH2["Receivables Aging\nRecharts StackedBarChart\ncurrent/30d/60d/90d+"]
    ROW2 --> CH3["Expenses by Category\nRecharts PieChart (donut)\nper-category breakdown"]

    ROW3 --> TBL["Recent Transactions\nRecharts Table\nlast 5 transactions"]
    ROW3 --> QA["Quick Actions\nNew Invoice\nNew Expense\nImport Bank Statement"]
```

### Invoices List
- **Route:** `/invoices`
- **File:** `app/(dashboard)/invoices/page.tsx`
- **Purpose:** Invoice management with search, filter, sort
- **Key Features:**
  - Status filter (all/draft/sent/paid/overdue)
  - Search by customer name or invoice number
  - Date range filter (this month, last month, quarter, all)
  - Sortable columns (number, customer, date, due date, amount)
  - Row actions (view, edit, send, download PDF, delete)
  - Summary row with totals by status
- **Data Requirements (Future API):**
  - `GET /api/invoices?status=X&search=Y&dateRange=Z&sort=field&dir=asc` — filtered/sorted invoice list
  - `PATCH /api/invoices/:id` — update invoice
  - `DELETE /api/invoices/:id` — delete invoice
  - `POST /api/invoices/:id/send` — send invoice via email
  - `GET /api/invoices/:id/pdf` — generate PDF
- **Current State:** Mock data, client-side filtering/sorting
- **Mobile Responsive:** Table scrolls horizontally, filters stack vertically

### Invoice Creation Wizard
- **Route:** `/invoices/new`
- **File:** `app/(dashboard)/invoices/new/page.tsx`
- **Purpose:** 6-step wizard to create and send invoices
- **Steps:**
  1. **Customer Selection** — Select existing customer or add new (dialog)
  2. **Invoice Details** — Invoice number, issue/due dates, net terms, currency
  3. **Line Items** — Add/remove items (description, qty, unit price, VAT rate), auto-calculate totals
  4. **Customization** — Optional notes and payment terms
  5. **Preview** — Visual preview of generated invoice
  6. **Send** — Email form (to, subject, message, copy to self) + save/download options
- **Data Requirements (Future API):**
  - `GET /api/customers` — customer list for dropdown
  - `POST /api/customers` — create new customer
  - `POST /api/invoices` — create invoice (draft)
  - `POST /api/invoices/:id/send` — send invoice via email
  - `GET /api/invoices/:id/pdf` — download PDF
- **Form Validation:**
  - Step 1: Customer required
  - Step 3: At least one line item with description required
  - Step 6: Email address required
- **Current State:** Mock data, local state, no persistence
- **Mobile Responsive:** Wizard steps adapt, form fields stack on mobile

### Expenses List
- **Route:** `/expenses`
- **File:** `app/(dashboard)/expenses/page.tsx`
- **Purpose:** Expense tracking with categorization and approval workflow
- **Key Features:**
  - Period filter (this month, last month, quarter, year)
  - Category filter (Office, Travel, Meals, Utilities, Marketing, Infrastructure, Software, Professional Services)
  - Search by description or vendor
  - Status badges (pending, approved, paid)
  - Receipt attachment indicator
  - Add Expense dialog (with upload placeholder)
  - Summary stats (total, pending, approved, paid counts)
- **Data Requirements (Future API):**
  - `GET /api/expenses?period=X&category=Y&search=Z` — filtered expense list
  - `POST /api/expenses` — create expense
  - `PATCH /api/expenses/:id` — update expense status
  - `POST /api/expenses/:id/receipt` — upload receipt (multipart)
  - `GET /api/expenses/:id/receipt` — download receipt
- **Form Fields:**
  - Amount + currency (EUR, RSD, BAM)
  - Category (dropdown)
  - Date
  - Vendor (searchable input)
  - Payment method (Cash, Card, Bank Transfer)
  - Receipt upload (placeholder UI)
  - Description (optional)
- **Current State:** Mock data, form submits to console
- **Mobile Responsive:** Filters stack, table scrolls

### Purchases (Alias)
- **Route:** `/purchases`
- **File:** `app/(dashboard)/purchases/page.tsx`
- **Purpose:** Alias to expenses page
- **Current State:** Same component as `/expenses`

### Banking
- **Route:** `/banking`
- **File:** `app/(dashboard)/banking/page.tsx`
- **Purpose:** Bank account management and reconciliation
- **Key Features:**
  - 3 tabs: Accounts, Reconcile, Transactions
  - **Accounts Tab:** List of bank accounts with balances (multiple currencies)
  - **Reconcile Tab:** Unreconciled transactions with match confidence, period selector
  - **Transactions Tab:** All bank transactions (chronological)
  - Import Transactions button (placeholder)
  - Match actions (approve, link, create new)
- **Data Requirements (Future API):**
  - `GET /api/bank-accounts` — list accounts
  - `POST /api/bank-accounts` — add account
  - `GET /api/bank-accounts/:id/transactions?reconciled=false` — unreconciled transactions
  - `POST /api/bank-accounts/:id/import` — CSV import
  - `POST /api/bank-accounts/:id/transactions/:txId/reconcile` — mark reconciled
  - `POST /api/bank-accounts/:id/transactions/:txId/link?invoiceId=X` — link to invoice/expense
- **Match Confidence Logic:** Visual indicators for 0%, <50%, 50-89%, 90%+
- **Current State:** Mock data, no reconciliation logic
- **Mobile Responsive:** Tabs stack, tables scroll

### Reports Hub
- **Route:** `/reports`
- **File:** `app/(dashboard)/reports/page.tsx`
- **Purpose:** Financial report selection and P&L preview
- **Report Cards:**
  - Profit & Loss (implemented at `/reports/profit-loss`)
  - Balance Sheet (coming soon)
  - Cash Flow Statement (coming soon)
  - VAT/PDV Report (live at `/reports/vat`)
  - Trial Balance (coming soon)
  - General Ledger (coming soon)
- **P&L Preview:**
  - Expandable Revenue/Expenses sections
  - Current month detailed breakdown
  - Export buttons (PDF, Excel) — placeholders
- **Data Requirements (Future API):**
  - `GET /api/reports/pl?month=YYYY-MM` — P&L report data
  - `GET /api/reports/balance-sheet?date=YYYY-MM-DD` — balance sheet
  - `GET /api/reports/cash-flow?period=X` — cash flow statement
- **Current State:** Only P&L and VAT reports implemented, others show "Coming Soon" badge
- **Mobile Responsive:** Report cards grid adapts

```mermaid
graph TD
    RH["Reports Hub\n/reports"]

    RH --> PL["Profit & Loss\n/reports/profit-loss\nLIVE — expandable revenue/expenses\nfetches from API with mock fallback"]
    RH --> BS["Balance Sheet\nCOMING SOON"]
    RH --> CF["Cash Flow Statement\nCOMING SOON"]
    RH --> VAT["VAT/PDV Report\n/reports/vat\nLIVE — 3-step wizard"]
    RH --> TB["Trial Balance\nCOMING SOON"]
    RH --> GL["General Ledger\nCOMING SOON"]

    PL --> PL_R["Revenue Section\n(expandable, breakdown by category)"]
    PL --> PL_E["Expenses Section\n(expandable, breakdown by category)"]
    PL --> PL_NP["Net Profit + Margin"]
    PL --> PL_EX["Export PDF / Export Excel"]

    VAT --> VAT_S1["Step 1: Reconciliation Check\n(warn if unreconciled transactions)"]
    VAT --> VAT_S2["Step 2: VAT Audit\n(all VAT transactions table)"]
    VAT --> VAT_S3["Step 3: Return Summary\nBox 1 / Box 2 / Box 3"]

    classDef live fill:#1e3a2f,color:#a6e3a1,stroke:#a6e3a1
    classDef soon fill:#2a1e2e,color:#888,stroke:#555
    class PL,VAT live
    class BS,CF,TB,GL soon
```

### VAT Report
- **Route:** `/reports/vat`
- **File:** `app/(dashboard)/reports/vat/page.tsx`
- **Purpose:** 3-step VAT return preparation
- **Steps:**
  1. **Reconciliation Check** — Warns if unreconciled bank transactions exist
  2. **VAT Audit** — Table of all VAT transactions (invoices + expenses) with net/VAT amounts
  3. **Return Summary** — VAT return boxes (Box 1: collected, Box 2: paid, Box 3: net due)
- **Data Requirements (Future API):**
  - `GET /api/bank-accounts/unreconciled-count` — reconciliation status
  - `GET /api/vat/transactions?period=YYYY-MM` — all VAT transactions
  - `GET /api/vat/return?period=YYYY-MM` — calculated VAT return data
  - `POST /api/vat/submit` — e-filing (Phase 2)
  - `GET /api/vat/export/pdf` — PDF export
  - `GET /api/vat/export/xml` — XML for e-filing
- **Calculations:** Assumes 20% standard VAT rate, converts all currencies to EUR equivalent
- **Current State:** Mock data, no submission, export placeholders
- **Mobile Responsive:** Tabs adapt, tables scroll, boxes stack

### Settings
- **Route:** `/settings`
- **File:** `app/(dashboard)/settings/page.tsx`
- **Purpose:** Multi-section settings page
- **Sections:**
  1. **Company** — Company profile (name, legal form, address, tax ID, currency, fiscal year)
  2. **Users** — User management table (name, email, role, status), invite button
  3. **Tax & Compliance** — Country, VAT registration, VAT number/rate, compliance reminders
  4. **Integrations** — Connected integrations (Intesa Bank CSV, Email SMTP), available integrations (Stripe, Fiken, Google Sheets, Slack, DocuSeal)
  5. **Notifications** — Email and in-app notification preferences
  6. **Security** — 2FA, session timeout, password policy, audit log, data export, delete company
- **Data Requirements (Future API):**
  - `GET /api/settings/company` — company data
  - `PATCH /api/settings/company` — update company
  - `GET /api/users` — user list
  - `POST /api/users/invite` — invite user
  - `GET /api/settings/tax` — tax settings
  - `PATCH /api/settings/tax` — update tax settings
  - `GET /api/integrations` — integration list
  - `POST /api/integrations/:id/connect` — connect integration
  - `GET /api/settings/notifications` — notification preferences
  - `PATCH /api/settings/notifications` — update preferences
  - `GET /api/security/audit-log` — audit log
  - `POST /api/security/data-export` — request data export
  - `DELETE /api/company` — delete company
- **Current State:** Mock data, form submits to console
- **Mobile Responsive:** Sidebar nav stacks, forms adapt

---

## Authentication Flow

```mermaid
sequenceDiagram
    participant U as User
    participant AP as AuthProvider
    participant AS as useAuthStore
    participant R as Router
    participant API as Backend API

    U->>AP: Navigate to /dashboard
    AP->>AS: checkAuth()
    AS->>API: GET /api/auth/me (Bearer token)

    alt API not configured (demo mode)
        AP-->>U: Render page directly (demoFallback=true)
    else Token valid
        API-->>AS: 200 OK — user data
        AS-->>AP: isAuthenticated=true
        AP-->>U: Render protected page
    else Token invalid / no token
        API-->>AS: 401 Unauthorized
        AS-->>AP: isAuthenticated=false
        AP->>R: router.replace('/login')
        R-->>U: Redirect to /login
        U->>U: Enter email + password
        U->>AS: login(email, password)
        AS->>API: POST /api/auth/login
        API-->>AS: 200 OK — JWT token
        AS->>R: router.push('/dashboard')
        R-->>U: Redirect to /dashboard
    end
```

---

## Screenshot Descriptions

### Dashboard
User sees:
- 3 metric cards at top (cash balance with green arrow, revenue MTD, unpaid invoices with warning badge)
- 3 charts in row below (P&L bar chart, receivables aging stacked bar, expenses donut)
- Bottom row: recent transactions table on left, quick action buttons on right

### Invoices List
User sees:
- Header with "Invoices" title and "New Invoice" button
- Filter row (status dropdown, search input, date range dropdown)
- Table with all invoices (sortable columns, status badges, action menu per row)
- Summary bar at bottom showing totals by status

### Invoice Wizard
User sees:
- Progress bar with 6 steps at top
- Current step content in card below
- Back/Next buttons at bottom (Send on final step)
- Step 3 shows line items with add/remove, running total calculation
- Step 5 shows formatted invoice preview

### Expenses
User sees:
- "Expenses" header with "Add Expense" button
- Filters (period, category, search)
- Table with date, description, category, amount, vendor, status badge, receipt icon
- Summary bar with totals (total €, pending count, approved count, paid count)
- Add dialog: form with amount+currency, category, date, vendor, payment method, receipt upload, description

### Banking
User sees:
- 3 tabs: Accounts, Reconcile, Transactions
- Accounts tab: table of bank accounts with type, currency, balance
- Reconcile tab: account selector, period, unreconciled transaction table with match confidence indicators, action buttons (✓ approve, link, create)
- Transactions tab: full transaction history with reconciled status

### VAT Report
User sees:
- 3-step tabs at top
- Step 1: Warning card if unreconciled transactions exist, "Reconcile Now" and "Continue" buttons
- Step 2: VAT transaction table (type badge, net amount, VAT rate, VAT amount), summary boxes (collected, paid, net due)
- Step 3: VAT return boxes (Box 1, Box 2, Box 3 highlighted), export buttons (PDF, XML), submit button (disabled, "Coming in Phase 2")

### Settings
User sees:
- Sidebar nav on left (6 sections)
- Content area on right showing active section
- Company section: form fields for company data
- Users section: table with invite button
- Integrations section: connected integrations cards, available integrations grid
- Security section: danger zone at bottom (delete company, red border)

---

## Notes

- **All pages use mock data** from `lib/mock-data.ts`
- **Authentication** implemented via `AuthProvider` + `useAuthStore` — demo mode active when `NEXT_PUBLIC_API_URL` not set
- **No persistence** — refreshing page loses all changes
- **Mobile-first design** — all pages tested at mobile/tablet/desktop breakpoints
- **Dark sidebar + light content area** — consistent layout across all pages