Finza

Next.js fintech superapp — code-verified technical documentation

v1.0.0Next.js 16React 19TypeScriptTailwind v4PWA

1. Introduction

Finza is a modern, scalable fintech superapp built with Next.js 16 App Router, TypeScript, Tailwind CSS 4, and React 19.2.

This documentation is generated from real source inspection: routes, stack versions, storage keys, and PWA behavior are aligned with actual code.

Pages

Layouts

Components

100%

TypeScript

2. Key Features

App Router Architecture

Organized route groups: (auth), (main), (myCard), (profile), (homePaiges), etc.

Authentication Journey

Money & Payment Flows

Send money, add contacts, make payments, scan-to-pay, and exchange currency.

Card Management

Add new card, card details, change PIN, set limits.

PWA Runtime

Custom service worker caching, install banner logic, and offline fallback.

Dark Themed UI

Tokenized color system in globals.css with Tailwind v4 @theme variables.

Frontend-Only Data Layer

No centralized API client yet; state handled with localStorage/sessionStorage.

Install Experience

Cross-platform install handling for Android/Desktop and manual iOS instructions.

3. Quick Start

Requirements

Node.js 18.17+
npm 9+ or pnpm 8+
Git

Installation

# 1. Install dependencies

npm install

# 2. Start development server

npm run dev

# 3. Open in browser

http://localhost:3000

Available Scripts

Script	Description
`npm run dev`	Start the Next.js dev server
`npm run build`	Create the production build
`npm run start`	Serve the production build
`npm run lint`	Run ESLint checks across the project

4. Folder Structure

Finza-next/Project root

src/app/Next.js App Router pages, layouts, route groups

src/components/Reusable UI components (Button, Card, Navbar, etc.)

src/styles/CSS/Tailwind/custom styles

src/lib/Database, utility, helper files

src/hooks/Custom React hooks

src/utils/Utility/helper functions

src/types/TypeScript types/interfaces

src/constants/App-wide constants/config

src/services/API clients, service layer

src/context/React context providers

src/store/State management (Redux, Zustand, etc.)

src/api/Next.js API routes (if needed)

public/Static assets, manifest, sw.js

package.jsonDependencies and scripts

5. All Pages (44)

Core

Route	Description
`/`	App entry route
`/splash`	Splash screen
`/onbording`	Onboarding flow

Utility

Route	Description
`/documentation`	Project documentation page
`/(homePaiges)/confirmation`	Confirmation page
`/terms-condition`	Terms & Conditions

Authentication

Route	Description
`/(auth)/signin`	Sign in page
`/(auth)/account-create`	Account creation
`/(auth)/forgot-password`	Forgot password
`/(auth)/create-new-password`	Create new password
`/(auth)/verification-code`	Verification code
`/(auth)/citizenship`	Citizenship verification
`/(auth)/identity`	Identity verification
`/(auth)/proof-of-identity`	Proof of identity upload

Main

Route	Description
`/(main)/home`	Main home page
`/(main)/my-cards`	My cards dashboard
`/(main)/profile`	Profile page
`/(main)/statistic`	Statistics page

MyCard

Route	Description
`/(myCard)/add-new-card`	Add new card
`/(myCard)/card-details`	Card details
`/(myCard)/change-pin`	Change card PIN
`/(myCard)/limits`	Card limits

Profile

Route	Description
`/(profile)/change-password`	Change password
`/(profile)/help-center`	Help center
`/(profile)/language`	Language settings
`/(profile)/notifications`	Notifications
`/(profile)/personal-data`	Personal data
`/(profile)/privacy-policy`	Privacy policy
`/(profile)/security`	Security settings

Money

Route	Description
`/(homePaiges)/(sent-money)/add-new-contact`	Add new contact
`/(homePaiges)/(sent-money)/beneficiary-list`	Beneficiary list
`/(homePaiges)/(sent-money)/invoice`	Invoice page
`/(homePaiges)/(sent-money)/send-money`	Send money
`/(homePaiges)/(sent-money)/send-to`	Send to contact
`/(homePaiges)/(sent-money)/transfer-success`	Transfer success
`/(homePaiges)/(sent-money)/verify-code`	Verify code for transfer

Payment

Route	Description
`/(homePaiges)/(payment)/apply-for-card`	Apply for card
`/(homePaiges)/(payment)/make-payment`	Make payment
`/(homePaiges)/(payment)/payment`	Payment page
`/(homePaiges)/(payment)/scan-pay-success`	Scan pay success
`/(homePaiges)/(payment)/scan-to-pay`	Scan to pay
`/(homePaiges)/(payment)/select-way`	Select payment way

Exchange

Route	Description
`/(homePaiges)/(convart)/exchange`	Currency exchange
`/(homePaiges)/exchange-success`	Exchange success

6. Project Analysis

Routing

The app has 44 page routes, grouped by feature domains and visibility scopes using App Router route groups.

Layouts

There are 4 layout files providing shared wrappers for root, auth, onboarding, and secure sub-sections.

State Persistence

Persistent state is primarily handled with localStorage and limited sessionStorage usage, not centralized context providers.

PWA Strategy

Custom public/sw.js is registered from src/components/pwa/ServiceWorkerRegister.tsx and pairs with /offline for fallback navigation.

This page intentionally avoids assumptions and only lists what is present in the current codebase.

7. User Flows

New User Onboarding

/splash
/onbording
/(auth)/account-create
/(auth)/verification-code
/(main)/home

Forgot Password

/(auth)/signin
/(auth)/forgot-password
/(auth)/verification-code
/(auth)/create-new-password
/(auth)/signin

Send Money

/(main)/home
/(homePaiges)/(sent-money)/add-new-contact
/(homePaiges)/(sent-money)/send-to
/(homePaiges)/(sent-money)/verify-code
/(homePaiges)/(sent-money)/transfer-success

PWA Install

/documentation
beforeinstallprompt
Install banner confirm
Standalone launch

8. Fonts & Typography

Primary

Roboto

Used for body text, headings, and utility classes throughout the app.

var(--font-sans)

Source

Local Font Files

Loaded via src/styles/fonts.css using @font-face declarations.

public/assets/fonts/*.woff2

Font tokens are defined in src/app/globals.css under @theme, and the Roboto faces are declared in src/app/fonts.css.

Font Sizes

Use	Size
Page title	`text-5xl / 48px`
Section header	`text-3xl / 32px`
Body	`text-sm / 14px`
Caption	`text-xs / 12px`

9. Customisation

Brand Colour

Change the primary brand colour in src/app/globals.css:

/* src/app/globals.css */
@theme {
--color-primary: #7B48FF; /* purple theme */
}

Adding a New Page

Create src/app/your-page/page.tsx.
Wrap content in a page-level container and style as needed.
Add route-level handling in layout and navigation if required.
If API data is required, add a new client in src/api/ first, because the folder is currently empty.

Replace mock data with real API calls by wiring a future API client into page components.

10. Data & State

Storage usage is key-based and page-driven. Prefixing is used mainly for auth, onboarding, and PWA keys.

localStorage

Key	Type	Purpose
`user`	JSON string	Logged-in user object
`token`	string	JWT or session token
`finza-pwa-dismissed`	"1"	PWA install banner dismissed
`finza-pwa-installed`	"1"	PWA install completed

sessionStorage

Key	Type	Purpose
`signupStep`	string	Tracks signup step in onboarding

Cookies / Server Session

No direct cookie write/read logic is currently implemented in client code. Session management is not centralized in this repository yet.

11. PWA Configuration

public/manifest.json

App metadata, icons, theme color, and shortcuts.

public/sw.js

Service worker cache rules for offline support.

src/app/offline/page.tsx

Offline fallback page when network is unavailable.

Service worker registration runs from src/components/pwa/ServiceWorkerRegister.tsx in src/app/layout.tsx, and install UX is handled by PwaBanner.tsx with localStorage keys finza-pwa-dismissed and finza-pwa-installed.

12. Credits & Libraries

Library / Resource	Version	Used For
Next.js	16.2.4	App Router, SSR, PWA
React	19.2.4	UI rendering
React DOM	19.2.4	DOM hydration
TypeScript	^5	Type safety
Tailwind CSS	^4.2.4	Utility-first CSS
@tailwindcss/postcss	^4.2.4	Tailwind PostCSS integration
Lucide React	^1.11.0	Icon set
@ducanh2912/next-pwa	^10.2.9	PWA support
ESLint	^9	Linting
eslint-config-next	16.2.4	Next.js lint rules

13. Support

If you have questions beyond this documentation, use the in-app support section.

Before reaching out, please:

Read this documentation thoroughly.
Check the browser console for errors.
Confirm you are running npm run dev, not opening files directly.
Ensure npm install completed without errors.

Tip: Missing NEXT_PUBLIC environment variables are the most common issue when integrating a real backend.