Modern web frontend for Kachingko - A comprehensive financial dashboard for transaction analysis, budgeting, and spending insights from your credit card statements.
- Interactive Dashboard — Real-time spending analytics with beautiful charts and visualizations
- Transaction Management — View, categorize, and search through all your financial transactions
- Budget Tracking — Set spending limits and monitor progress across categories
- Statement Upload — Drag-and-drop PDF statements with instant processing feedback
- Responsive Design — Seamless experience across desktop, tablet, and mobile devices
- Dark/Light Mode — Modern UI with theme switching capabilities
- RCBC
- EastWest
- BPI
- BDO
- Metrobank
- TypeScript — Type-safe JavaScript
- React 19 — UI library
- TanStack Start — Full-stack React framework
- TanStack Router — Type-safe routing
- TanStack Query — Data fetching and caching
- TanStack Form — Type-safe forms
- Tailwind CSS — Utility-first CSS framework
- shadcn/ui — Beautifully designed components
- Radix UI — Unstyled, accessible UI primitives
- Vite — Next generation frontend tooling
- Zod — TypeScript-first schema validation
- Node.js 22.17+
- npm, yarn, or pnpm
- Kachingko API running locally
We recommend using nvm (Node Version Manager) to manage Node.js versions for consistency across environments.
Install nvm:
# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# Reload your shell profile
source ~/.bashrc
# or for zsh users:
source ~/.zshrc
# Verify installation
nvm --versionInstall Node.js:
# Install Node.js LTS
nvm install 22.17.0
nvm use 22.17.0
nvm alias default 22.17.0
# Verify installation
node --version
npm --versionCreate .env.local:
# API Configuration
API_URL=http://localhost:8888
# Generate session secret via node
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
SESSION_PASSWORD=# Clone repository
git clone https://github.com/braynm/kachingko-web.git
cd kachingko-web
# Install dependencies
npm install
# Start development server
npm run devApplication will be available at http://localhost:3333
npm run dev # Start development server.
── app
│ ├── components
│ │ ├── AppSidebar.tsx
│ │ ├── EmptyData.tsx
│ │ ├── ThemeSwitcher
│ │ ├── layout
│ │ └── ui
│ ├── pages
│ │ ├── LoginPage.tsx
│ │ ├── SignupPage.tsx
│ │ ├── SpendingHighlightsPage
│ │ ├── TxnPage
│ │ └── TxnUploadPage
│ ├── routeTree.gen.ts
│ ├── routes
│ │ ├── __root.tsx
│ │ ├── _authenticated
│ │ ├── _authenticated.tsx
│ │ ├── _unathenticated
│ │ ├── _unathenticated.tsx
│ │ └── index.tsx
│ ├── server
│ │ └── session.ts
│ └── styles
│ └── app.css
├── hooks
│ ├── use-mobile.ts
│ └── user-transaction.ts
├── lib
│ ├── auth
│ │ └── index.ts
│ ├── hooks
│ │ └── query.ts
│ ├── session
│ │ └── index.ts
│ └── utils
│ ├── amount.ts
│ ├── api.ts
│ ├── cn.ts
│ └── date.ts
└── router.tsx
# Add shadcn/ui components
npx shadcn-ui@latest add button
npx shadcn-ui@latest add card
npx shadcn-ui@latest add dialog
# Components will be added to app/components/ui/The app combination of TanStack Query + TanStack Server functions for data fetching. API services are located in routes/<page name>:
// Example: app/services/transactions.ts
import { useQuery } from '@tanstack/react-query'
export const useTransactions = () => {
return useQuery({
queryKey: ['transactions'],
queryFn: () => fetch('/api/transactions').then(res => res.json()),
})
}TanStack Router provides file-based routing with type safety:
// app/routes/transactions/index.tsx
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/transactions/')({
component: TransactionsPage,
})
function TransactionsPage() {
return <div>Transactions Dashboard</div>
}The project uses Tailwind CSS with a custom design system:
// Example component with Tailwind classes
export function DashboardCard({ children, className, ...props }) {
return (
<div
className={cn(
"rounded-lg border bg-card text-card-foreground shadow-sm",
className
)}
{...props}
>
{children}
</div>
)
}Forms use TanStack Form with Zod validation:
import { useForm } from '@tanstack/react-form'
import { zodValidator } from '@tanstack/zod-form-adapter'
import { z } from 'zod'
const budgetSchema = z.object({
category: z.string().min(1, 'Category is required'),
amount: z.number().positive('Amount must be positive'),
})
export function BudgetForm() {
const form = useForm({
defaultValues: {
category: '',
amount: 0,
},
validatorAdapter: zodValidator,
})
// Form implementation...
}# Build the application
npm run build
# Preview the production build
npm run preview
# Start production server
npm run startThe build creates .output/ directory that can be deployed to any hosting service:
- Vercel
- Netlify
- Cloudflare Pages
- AWS S3 + CloudFront
# Run all tests
npm run test
# Run tests in watch mode
npm run test:watch
# Run tests with coverage
npm run test:coverageContributions are welcome! Please read our contributing guide.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'feat: add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- API: kachingko-api - Backend Elixir/Phoenix API
- Docs: kachingko-docs - Documentation
This project is licensed under the Apache 2.0 - see the LICENSE file for details.
- Documentation: kachingko-docs
- API Docs: kachingko-api
- Discussions: GitHub Discussions