NKKakeist

Turn messy financial exports into trustworthy, explainable personal finance records.

Comment

NKKakeist

Turn complex payment flows into trustworthy, explainable personal finance records.

Inspiration

NKKakeist started with a problem I experienced firsthand: existing personal finance services do not always handle modern payment flows well.

Personal finance data is rarely clean or consistent. Banks, credit cards, QR-code payment services, prepaid e-money, investment accounts, pensions, and reward-point programs all describe money differently. Some transactions are not meaningfully supported by existing services, while others become difficult to understand when several payment methods are combined.

For example, Mobile Suica can be charged from a credit card or funded through a bank-related payment flow. A purchase made from that prepaid balance may therefore appear across multiple services:

  1. a charge from a credit card to Mobile Suica;
  2. the actual purchase made with the Mobile Suica balance; and
  3. the later bank withdrawal used to pay the credit-card bill.

Only the purchase should normally be counted as spending. The charge and the card payment are movements between accounts that I own or track. However, with default settings in some finance services, more than one of these records can be treated as an expense, causing double counting.

The same confusion occurs with QR-code payments, prepaid balances, credit-card payments, bank-funded charges, investment contributions, and reward points. I wanted a system that could represent these flows accurately and show me why each record was classified in a particular way.

That is why I built NKKakeist: not simply to automate bookkeeping, but to turn fragmented financial exports into records that are explainable, reviewable, and safe to correct.

What it does

NKKakeist is a personal finance and asset-management web application that:

  • manages cash, bank, credit-card, e-money, payment-service, investment, pension, liability, and reward-point accounts;
  • tracks income, expenses, and transfers without double-counting internal movements;
  • distinguishes real spending from credit-card payments, prepaid charges, payment-service reallocations, and investment contributions;
  • imports Money Forward transaction CSV files, balance snapshots, per-security valuations, and asset-history data;
  • imports Mobile Suica statements directly from PDF files;
  • supports semi-automated JRE POINT imports;
  • validates imported data before committing it;
  • detects duplicate and unresolved rows and explains the reason at row level;
  • provides category suggestions and reusable classification rules;
  • reconciles calculated balances with official balances; and
  • displays monthly and yearly income, expenses, assets, liabilities, net worth, account balances, and security-level trends.

The core design principle is simple: if the system cannot explain imported financial data, it should not commit it automatically.

The problem

The hardest problem is not parsing a CSV file. It is reconstructing one real-world flow of money from records produced independently by several financial services.

A credit-card charge to a prepaid account is not necessarily an expense. A bank withdrawal that pays a credit-card bill is not a second purchase. Money sent to an investment account is not ordinary consumption. Point usage may reduce the cash portion of a purchase without making the purchase disappear.

Simple imports frequently lose these distinctions. Overlapping export periods, duplicate files, incomplete rows, changing formats, and unsupported transactions add further risk. Automatically accepting every row may produce a clean-looking dashboard whose totals cannot actually be trusted.

The solution

NKKakeist uses a staged import workflow instead of writing external data directly into the transaction ledger.

Imported rows move through parsing, normalization, validation, preview, and confirmation. Before anything is committed, the user can review classifications, transfer matches, duplicate candidates, unresolved rows, and their expected effect on balances.

The application models connected payment events as a flow rather than as unrelated expenses. It can retain the history of money moving between accounts while ensuring that only the actual purchase affects household spending.

When a case cannot be classified safely, NKKakeist leaves it unresolved for human review. Once confirmed, the decision can become a reusable rule for future imports. This creates a practical cycle of review, correction, and gradual automation without sacrificing traceability.

How I built it

NKKakeist is built with:

  • PHP and Laravel 13;
  • Inertia.js;
  • React;
  • TypeScript;
  • Tailwind CSS;
  • MySQL;
  • Docker Compose; and
  • custom CSV and PDF import pipelines.

I deliberately chose PHP and Laravel for the backend. I already have professional experience with PHP frameworks, so this choice allowed me to spend the limited build time on the difficult domain rules, data integrity, and product behavior rather than learning an unfamiliar backend stack for its own sake.

Using a technology I understand also meant that I could critically review code proposed by Codex. I remained responsible for architectural decisions, security, database consistency, and deciding when an automated classification was safe enough to use.

At the same time, I did not want the application to feel like a traditional server-rendered PHP system. I combined Laravel with React, TypeScript, Inertia.js, and Tailwind CSS to create a modern, component-based interface with SPA-like navigation and type-aware frontend development.

This architecture keeps Laravel's strengths—routing, authentication, validation, ORM, and domain modeling—while enabling reusable React components, responsive screens, interactive import previews, and data-rich dashboards. Inertia.js connects both sides without requiring a separate API layer for every screen.

The result is intentionally pragmatic: a backend based on technology I know well, paired with a contemporary frontend architecture that makes the application easier and more pleasant to use.

How I used Codex and GPT-5.6

The initial foundation of NKKakeist was developed with Codex using GPT-5.5. From July onward, I used Codex with GPT-5.6 throughout the main implementation and expansion of the project.

Codex and GPT-5.6 helped me:

  • analyze edge cases found in real financial records;
  • turn ambiguous payment behavior into explicit domain rules;
  • design the staged import architecture;
  • implement Money Forward, Mobile Suica PDF, and JRE POINT import logic;
  • model assets, liabilities, net worth, and security valuations;
  • implement transfer matching, duplicate detection, and reconciliation;
  • investigate the impact of changes across the application;
  • improve database queries and frontend behavior;
  • write and expand automated tests;
  • verify workflows and rendering in the browser; and
  • organize documentation and changes into small, auditable commits.

GPT-5.6 was particularly useful when a change involved several connected account types and existing classification rules. It could maintain the wider context, identify possible double-counting paths, and help translate an observed inconsistency into implementation and test cases.

I did not treat Codex as an autonomous authority over financial behavior. I supplied the real-world cases, challenged proposed rules, reviewed the generated code, and made the final decisions about classifications and safe commit conditions. Codex accelerated analysis, implementation, testing, and review; it did not replace domain judgment.

A note on authorship

This submission is not an untouched block of AI-generated marketing text. Its problem statement comes from my own experience using personal finance services, and the technical choices and product decisions described here are decisions I made while building NKKakeist. I used AI to help translate, structure, and refine the English, then reviewed and edited the submission so that it accurately represents the project and my intent.

That human-and-AI collaboration is also how the application itself was built: I provided the experience, requirements, judgment, and final review, while Codex helped me work through implementation and verification more quickly.

Challenges I ran into

Separating spending from transfers

Credit-card payments, QR-code payment charges, prepaid e-money charges, investment contributions, and reward-point usage can resemble expenses even when they are internal movements or partial settlement methods. A rule that works for one provider may be incorrect for another.

Handling untrusted and overlapping imports

External files can be duplicated, incomplete, partially overlapping, or changed by their provider. NKKakeist must detect these cases without silently creating incorrect transactions.

Preserving explainability

It would have been easier to maximize automatic classification and hide uncertainty. Instead, I designed the system to expose applied rules, duplicate reasons, unresolved states, and balance differences. This required more domain modeling and UI work, but it makes the result trustworthy.

Modernizing without discarding proven experience

I wanted to use my PHP experience rather than replace it merely to follow a trend, while still delivering a modern product experience. Laravel, Inertia.js, React, and TypeScript provided a practical balance between backend confidence and contemporary frontend development.

What I am proud of

Explainability before automation

NKKakeist shows which rule was applied, why a row was considered a duplicate, and why a record could not be committed. A high automatic-import rate is not useful if the resulting balance cannot be explained.

Deterministic duplicate detection

Duplicate detection is based on reproducible attributes such as date, amount, account, description, source, and import context. It does not depend only on an opaque AI judgment, so the same input produces a consistent result that can be investigated.

Transaction and balance reconciliation

The application tracks both transactions and official balance snapshots. Comparing calculated and official balances helps reveal missing transactions, incorrect classifications, and import gaps.

Safe correction

Financial data will always contain exceptions. NKKakeist is designed around previewing, correcting, and reusing confirmed rules rather than pretending every case can be classified perfectly on the first attempt.

Testing

I used automated tests for important domain behavior, including:

  • importing the same data more than once without duplicating transactions;
  • importing files with overlapping date ranges;
  • preventing a purchase and its later credit-card payment from becoming two expenses;
  • treating e-money and payment-service charges as transfers where appropriate;
  • refusing to commit unknown or incomplete rows automatically;
  • leaving official data unchanged when an import preview is cancelled;
  • detecting differences between calculated and official balances; and
  • calculating assets, liabilities, and net worth consistently.

I also used Codex-assisted browser verification to test complete workflows, screen transitions, validation messages, import previews, and dashboard results. Realistic financial patterns were especially important because isolated unit cases do not reveal every multi-account interaction.

Demo instructions

  1. Open the account list and review the different account types, including bank, credit card, prepaid e-money, payment service, and investment accounts.
  2. Open the import screen and select a Money Forward CSV file or Mobile Suica PDF.
  3. Review the parsed rows in the pre-commit preview.
  4. Inspect classifications, transfer matches, duplicate candidates, and unresolved reasons.
  5. Confirm only the valid rows and verify that they appear in the transaction ledger.
  6. Import the same data again and confirm that the application detects the duplicates.
  7. Open balance reconciliation and compare calculated balances with official snapshots.
  8. Open the dashboard to review monthly and yearly income, expenses, assets, liabilities, and net worth.
  9. Open the investment view to review account-level and security-level valuation trends.
  10. Create or update a classification rule and confirm that it is reused on a later import.

What I learned

For personal finance software, automation is valuable only when users can understand and verify its output.

Preview, traceability, deterministic duplicate detection, balance reconciliation, and safe correction are more important than accepting every row automatically. A trustworthy system must be willing to say, “This transaction is not resolved yet.”

I also learned that AI-assisted development is most effective when the developer has a strong basis for reviewing the result. My PHP and Laravel experience let me evaluate backend proposals critically, while Codex and GPT-5.6 helped me move faster across unfamiliar or broad areas such as frontend refinement, impact analysis, test expansion, and browser verification.

What's next

Next, I plan to:

  • improve investment valuation and profit/loss analysis;
  • expand long-term net-worth trends and forecasting;
  • provide portfolio analysis across assets and liabilities;
  • further automate Mobile Suica and JRE POINT update workflows;
  • acquire data through authenticated browser sessions;
  • detect unusual spending and unexplained balance differences;
  • improve classification suggestions; and
  • provide a judge-friendly demo environment with safe sample data.

Even as data acquisition becomes more automated, NKKakeist will preserve its validate, preview, and human-confirmation workflow.

Built with

PHP, Laravel 13, Inertia.js, React, TypeScript, Tailwind CSS, MySQL, Docker Compose, Codex, and GPT-5.6.

Built With

Share this project:

Updates