Wealth management platform connecting investors with a professional wealth-advisory company, allowing investors to answer a questionnaire and receive either a recommended model portfolio or a custom-tailored individual portfolio, that is further monitored, rebalanced and adjusted by a professional wealth-adviser based on the changing market conditions and client’s goals.
The top-down migration playbook
Almost every firm that decides to leave its portfolio-accounting platform starts by drawing the same plan on a whiteboard: extract everything, rebuild it somewhere better, pick a weekend, switch.
That version of a platform migration has a poor record in financial services, and the reason is not engineering competence. You are not replacing an application; you are replacing a book of record whose outputs are read by clients, auditors and regulators, and whose history has to remain defensible afterwards. A consumer app can ship a bug and fix it by Tuesday. A performance figure that changes after a client has seen it is a different category of event.
There is a second plan, and it is the one we recommend to every firm in this position. Build downwards, not outwards. Start at the layer your users touch, put it on a copy of the data that you own, and leave the incumbent running underneath as the system of record. Then buy the expensive layer in instalments. The principle underneath the whole playbook fits in one line: move ownership down the stack, one layer at a time.
Done this way, top-down migration gives the firm four things before the incumbent is replaced: control of the client experience; ownership of its historical data layer; the ability to add new sources without waiting on the incumbent; and a reversible path instead of a one-time cutover. Everything below is the engineering detail that makes those four real.
The top-down migration, stage by stage. Bold marks what you own and can change; everything else is still the vendor’s:
| Layer of the pipeline | Stage 0 – Today | Stage 1 – Own the copy | Stage 2 – Add sources beside it | Stage 3 – Retire it, market by market |
| Advisor & client experience | vendor | rebuilt | yours | yours |
| Reporting | vendor | your engine | yours | yours |
| Analytics & performance | vendor | recomputed | recomputed + reconciled | yours |
| Your data store | not yours | nightly copy | multi-source | system of record |
| Reconciliation & golden record | vendor | vendor | across sources | yours |
| Extraction & normalisation | vendor | vendor | your extraction | yours |
| Bank & custodian connections | vendor | vendor | vendor + new sources | direct + by choice |
| Share of the pipeline you own | none | the top of the stack | most of it | all of it |
| What the business has | Advisors stitch the view by hand. Nothing is portable. | One consolidated view, live for advisors. Incumbent still runs. | Coverage beyond the incumbent. Multiple sources reconciled. | Connections under your control. Vendor dependency becomes a choice. |
Stage 1 – Own the copy
The first move is deceptively small: build your own interface, on your own data store, fed nightly from the incumbent. The incumbent remains the system of record. Nothing is switched off. Nobody migrates.
Four decisions here determine whether the rest of the roadmap is possible.
Sync, don’t call through. The temptation is to have the new interface call the incumbent’s API live. Don’t. These APIs are typically built for batch and reporting workloads, not for rendering a dashboard, and every live call makes your product exactly as fast and exactly as available as somebody else’s system. Extract on a schedule into a store you control, and serve every read from your own store.
The store is not a cache. Once you are landing a daily snapshot, you start accumulating a time series the incumbent will not sell you retrospectively – day-over-day movement, twelve-month trends, the ability to answer “what changed since Tuesday” without asking anyone. It also means the clock starts the night you switch the sync on. You cannot backfill a trend you never captured, which is an argument for starting the sync months before you need the analytics.
Normalise into your own domain model, not theirs. Put an anti-corruption layer between the incumbent’s shapes and yours, and model the whole entity hierarchy from day one – household, client, account group, registration, account – even if your first release displays only two of those levels. On one build, modelling the full hierarchy up front was a matter of hours. Retrofitting it later is a data migration. It is the cheapest insurance in the plan.
Keep the audit trail from the first commit. Every mirrored row keeps its source identifier, so any figure on a screen traces back to the record it came from. Alongside it, maintain a field-mapping dictionary: every source field used, the column it maps to, the transformation applied. Paperwork, yes – and also the contract that makes the sync auditable, and the artefact that makes a two-source comparison possible later.
What actually goes wrong when you pull data out
Nobody warns you about this part. This list is drawn from published vendor documentation and real integration work, and it generalises across most legacy portfolio-accounting platforms:
- Offset pagination collapses at scale. skip/top-style paging is fine for a few thousand records and times out somewhere past a few hundred thousand. The documented workaround on at least one major platform is to fetch identifiers only, chunk them into batches of tens of thousands, POST those batches to list endpoints, and tune the parallelism empirically.
- Hard record caps that fail dishonestly. Exceed a per-call limit and you may get “the query specified is not valid” rather than a clean 413 or 429. You will lose a day believing your query is malformed.
- Rate limits are undocumented. They are discovered by hitting them. Build circuit breakers and exponential backoff before you need them, and log every rejected call with its shape.
- Silent-failure traps. Case-sensitive field selectors that return nothing rather than erroring are common enough to plan for.
- Mixed API generations. Platforms that grew by acquisition run v1 and v2 endpoints with inconsistent response shapes side by side. You need per-endpoint mapping, not a generic client.
- Credentials are not self-service. Partner IDs, secrets, whitelisted redirect URLs and approval to unmask sensitive fields go through the vendor’s integrations team. Budget weeks, and put it on the critical path in writing — delays there move your delivery date day for day.
- Auth is often user-scoped, not application-scoped. There may be no application-level API key at all; the supported pattern is a dedicated service user with a non-expiring credential.
- One firm can be several databases. Enterprise tenants are sometimes split across multiple firm identifiers, each a separate database that must be queried separately.
- There are usually two paths, and you need both. A REST API for everyday volumes and a separate bulk or flat-file extract for anything above a few hundred thousand records. Design for both on day one; discovering the second in month four is a re-architecture.
The two timing problems
When to run. You cannot choose a cron hour until you know when the upstream finishes its own custodian reconciliation – and that is a window, not an instant. On one North American book it ran from roughly 4am to 10am Eastern. Schedule your extract relative to that window.
What “now” means. Custodian positions and transactions arrive by overnight batch. The freshest data most portfolio systems hold is previous-business-day close; intraday pricing is a different product from a different supplier. There is a subtler trap: where an incumbent does show a “real-time” custodian tile, it is usually reading straight from the custodian rather than from its own portfolio database – so two numbers inside the same vendor’s product can legitimately disagree intraday.
The engineering answer is to make freshness explicit and truthful:
- every figure on every screen carries its own “as of” date;
- if a nightly run fails, the portal keeps serving the last good snapshot with its date clearly displayed, and the run is re-executed from a documented runbook;
- the sync writes per-domain run records – timing, volumes, outcome – because a volume delta is the cheapest break detector you will ever get for free.
An advisor who can see that a number is from Friday will work with it. An advisor who discovers that a number they trusted was silently stale stops trusting the platform permanently.
The performance fork
At some point in stage 1 you face a decision that shapes everything after it. Performance and cost basis are usually not extractable rows – on most platforms, per their own developer documentation, they are produced by the accounting engine and served through a reporting interface, not stored on the position object. So you have two options.
Cache the incumbent’s answers. Request them through the reporting interface, store them, serve them fast. Your numbers match theirs by construction, because they are theirs. The cost: you have gained no independence in this layer, and the report path is asynchronous, so you will need your own job queue and your own progress feedback – the incumbent gives you neither.
Recompute them yourself. Now you own the model, and a reconciliation problem. Your time-weighted return will not match theirs to the basis point, because accrual treatment, intraday flow timing, fee handling and sub-period linking conventions all differ. Each of those differences is defensible. Explaining forty of them to an investment committee is not.
Our recommendation is unambiguous: cache in stage 1, recompute later, and never let recomputation happen by accident. Derive only what your own snapshots support cleanly – trends, movers, period deltas – and label precisely what is yours and what is the incumbent’s. When you do rebuild the return engine, treat it as a project with a parallel run and a sign-off, not as a side effect of a UI feature.
Two rules that keep the first release honest
Never fabricate a number to fill a screen. A domain you have not verified renders a clearly labelled placeholder behind a feature flag, and flips to live once the workflow is checked. This is also what incremental cutover looks like in practice: each data domain switches from placeholder to live independently, at its own pace, with its own verification.
Name the screen for what it contains. If held-away assets are not connected yet, the screen is called “managed portfolio,” not “total net worth.” Most portfolio systems hold only managed accounts; a genuine net-worth view needs aggregation or client-entered data you probably do not have in release one. The temptation to use the better label is strong. Resist it, and the platform’s credibility survives its own roadmap.
Stage 2 – Add sources beside it
Once the store exists and the interface reads only from it, adding a second source is an integration rather than a project.
This is where the abstraction gets tested. A connector contract with only one implementation is not a contract, it is a coincidence. The second source proves the canonical model holds – and it only holds if five things were made canonical before that source arrived:
- Instrument identity. One rule for what makes two records the same instrument – identifier hierarchy over ticker, always – so the same bond from two feeds lands as one holding.
- The entity hierarchy. Household, client, account group, registration, account – one graph every source maps into, whatever shape it arrives in.
- Currency treatment. One base-currency policy, one source of FX rates, dated – so a multi-currency position is comparable across sources.
- Timestamps and “as of” rules. One freshness convention per figure, so “yesterday’s close” means the same thing regardless of which feed supplied it.
- Source-precedence metadata. Every stored value knows where it came from, so when two sources disagree in stage 3, the rule that decides between them has something to work with.
If any of the five is missing, the second source does not join the platform – it forks it. Which second source is the right one is a question with a market-by-market answer rather than a global one.
It is also where you begin doing dual-source reconciliation whether you planned for it or not – the next stage’s problem, arriving early.
Stage 3 – Retire it, one market at a time
For portfolio-platform replacements, parallel running is the cutover pattern we recommend by default, and it needs four things decided before the second source goes live.
Tolerance, per asset class. A listed equity position that disagrees by one share is a break. A private-markets valuation that disagrees by a rounding cent is not. A single global tolerance produces either noise or blindness.
Precedence, in advance. For every field, a rule decides which source wins – written down before the first disagreement, not negotiated during it.
An exception queue with a memory. Breaks go to a person, the person decides once, and the rule remembers the decision. A reconciliation process that asks the same question every night is a process that will be ignored by week three.
A hold-back policy. An unresolved position is excluded from the consolidated view, flagged, and never silently averaged with its counterpart. A number an advisor cannot trace to a source is worse than a number that is visibly missing.
Then the exit gate. Nobody switches the old system off until breaks stay under tolerance for a set number of consecutive cycles; performance history has been recomputed and signed off by whoever owns the numbers; generated statements match the old ones line for line; and write paths, audit trail and access controls have been reviewed.
Retire per market, not globally. Each jurisdiction has its own sources, its own local rules and its own worst-case client conversation.
The boundary that actually matters: read to write
Everything in stages 1 and 2 is read-only, plus writes you own entirely – tasks, notes, goals, approvals. That is why it is cheap and safe.
The moment your platform writes into the financial domain – trade instructions, money movement, billing – the cost profile changes completely. What appears in the plan then is not screens. It is maker-checker approval workflow, an append-only audit log with tiered retention, durable queues with near-zero data loss for in-flight instructions, negative-path testing and financial-correctness QA.
This boundary is also where migration mechanics meet regulation. The two decisions below read like compliance detail, but they are migration decisions: each is cheap to settle in stage 1 and structural to change later.
Settle the records regime once. Advisory books-and-records rules and broker-dealer rules are different regimes with different storage requirements. Since the SEC’s 2022 amendments (Release No. 34-96034), a broker-dealer may satisfy the electronic-recordkeeping rule either with write-once storage or with an audit-trail alternative that “permits the recreation of an original record if it is modified or deleted” – but that is still a property of the storage system, chosen once, not bolted on later. If there is any chance regulated broker-dealer records will ever live on the platform, design for it up front. That is a month-one conversation with compliance, not a month-twenty one.
And note what this does to the migration itself: a platform change does not reset the retention clock. Under SEC Rule 204-2, advisory books and records are generally kept for five years from the end of the fiscal year during which the last entry was made, the first two years in an easily accessible place; under FINRA Rule 4511, records without a specified retention period default to six years. You remain obliged to produce records from the old system for the balance of those periods, which is why “cut over and archive the old thing” is not actually available to a regulated firm – and why parallel running is the cheap option, not the cautious one.
Settle tenancy once. How clients, entities and regions are isolated is an early, expensive, structural decision. Make it in stage 1 even if your first release has a single tenant, so later phases add screens rather than reworking the data model.
Why staged migration is safe, stated precisely
A disaster-recovery principle explains why this pattern is safe. Classify your data by whether it is rebuildable. Positions and transactions from a custodian feed are source data; losing them is a serious event. Performance figures, aggregated views and allocation calculations are derived – they can be reconstructed from upstream source data at any time. Losing recent derived figures is an inconvenience, not a client-harm event.
Which means the consolidation layer you are building is, by design, disposable and rebuildable, while the incumbent stays the durable record until you decide otherwise. That is precisely why the risk profile is nothing like a big-bang migration – and precisely why you can start on Monday.
Itexus builds wealth-management and capital-markets platforms: multi-custodian aggregation, portfolio analytics, reporting, advisory workflow and the intelligence layer on top of them. The playbook above starts with an extraction verdict on your incumbent – and that is also the natural first engagement: a short, scoped assessment of stage 1’s hardest layer, measured in weeks, that settles the budget question before anything larger is committed. If you are somewhere on this road – deciding, stuck, or mid-migration – a one-call conversation about your incumbent’s extractability is a useful place to start.