SK
Sathishkannan Labs
Explained simply • Built practically

Projects  /  FinReview - Portfolio intelligence platform for Indian investors  /  Architecture Decision

How an architecture audit changed FinReview before public release

17 Jul 2026 · 3 min read · By Sathishkannan methodology
Architecture Decision Record
Status
accepted
Context
FinReview was functionally complete and ready to deploy. Before tagging a public release, I used AI-assisted code review — Claude acting as a senior architect — to audit the codebase against what the README was actually claiming. The question was whether to ship the identified issues, remove the features, or handle them honestly.
Rationale
Honest feature scoping — returning HTTP 501 with a clear message, disabling frontend controls, and documenting limitations explicitly — is more credible than either shipping silent stubs or removing the architectural boundaries. The service boundaries for CAS import and overlap remain in the codebase; they define where a real implementation slots in for a future version.
Trade-offs
The released application is less feature-complete than the original design. CAS import and overlap are visible to users as disabled or labelled as estimated, which makes the limitations explicit rather than hidden. This is the correct trade-off for a project whose purpose is to demonstrate engineering judgment, not feature count.

Before releasing FinReview publicly, I subjected the codebase to an external architecture review using AI-assisted code analysis alongside my own verification. The goal was not validation — it was adversarial review. I wanted to find what was wrong before a recruiter or hiring manager did.

Four real problems surfaced.

The mutual fund overlap diagnostic was returning fabricated data. The backend used an MD5 hash of the user's fund names to generate a deterministic random overlap score between 20 and 75 percent, then returned hardcoded stock names from a fixed pool regardless of what funds the user actually held. The frontend rendered this with no disclaimer. A user had no way to know the numbers were invented.

The CAS PDF import appeared to work. The upload route accepted the file, accepted the password, and returned a success response — but it was silently importing two hardcoded transactions with today's date and ignoring the actual file completely. The success message read "Imported from CAS PDF!" The data was entirely fabricated.

The authentication token was never verified. The token issued at login was a plain string in the format token-{user_id}-{timestamp}. There was no signature and no verification. Any request with a valid user ID integer could read or modify any user's portfolio data without a valid token. 29 of 31 routes had no auth guard.

The forgot password endpoint returned a mock message implying an email would be sent. No email was ever sent. No reset token was generated.

None of these were edge cases. They were the core flows a user would hit on day one.

The decision I had to make was how to handle them. Three options existed. Ship them as-is and accept that users and reviewers would eventually discover the fabrication. Remove the features entirely. Or handle each one honestly — 501 responses with clear messages, disabled frontend controls, explicit documentation of what was not yet implemented.

I chose the third path. CAS import now returns HTTP 501. The frontend controls are disabled with "Disabled in v1.0.0" in the placeholder text. The overlap diagnostic is labelled "Estimated Diagnostic Preview" with an explicit note that it does not use live fund look-through data. Forgot password returns 501. Authentication now uses HMAC-signed tokens with 7-day expiry, verified on every protected route.

The biggest lesson was not technical.

A stub that returns a success message is worse than a 501. It does not just fail — it actively misleads. A user who uploads their CAS file and sees "Imported!" will trust data that does not exist. A portfolio reviewer who sees a 28 percent overlap score will think it means something. The technical implementation of the stub matters far less than the decision to be transparent about its limitations.

Software earns trust not because it has more features, but because it is honest about the features it has.

The versions tell the story cleanly. v1.0.0 was the original build. v1.0.1 addressed the audit findings. v1.0.2 added a startup warning for the default secret key and gated the admin shutdown endpoint behind authentication. Each version is a decision, not just a patch.

Using AI-assisted review to find these issues before release is itself part of the engineering approach I want this project to demonstrate. The same AI integration discipline that shaped the analytics architecture — keeping AI as an interpreter rather than a decision-maker — applies to the development process. AI finds the issues; the engineer decides what to do about them.

← Why financial calculations should never touch a la…