Getting familiar with the code and architecture in a new job

It takes me 20 minutes and if it requires a minute longer then you're not a 10x savant like I am and you're slowing everyone down. You don't deserve to work here.

JK. IME the cycle is

1. Daunting, complete confusion

2. Find 1 or 2 subsections where I know 100% what is going on.

3. Do work in those subsections, it works, but then something messes up

4. In finding how it messes up I discover the weird edge cases and issues with the code, try to fix it

5. Doing so I begin to understand how it's all put together

Repeat 2-5 over a few weeks until it everything comes into place.

What's most important is finding small, definable areas where you can sink your mental "hooks" into the logical/semantic aims of the code, so you're not spending brain power aiming to compress information too noisy in scope at that point in your knowledge of it.

It's hard for me to give you a direct answer to how long it takes (and besides, there's a lot here that's helpful already), so instead, here's how I try to understand new architecture/code-bases.

I start by drawing it out. At whatever level I'm familiar enough with and then get someone's opinion on my architecture diagram.

I do this a few times and it really accelerates my understanding of anything new.

It turns the problem of understanding the codebase to a problem of first mapping it.

Once it's been mapped, you can familiarise yourself with the various components you've mapped out.

Hope this helps! And good luck :-)

personally on large codebase, on first weeks i ask people what they're working on, then i ask intricate details on how things work on their end.

how does the auth work, how does state management work, whats the process on the design system, who's working on who, those kind of things.

on the macro scale i also ask the solution architects directly, on the micro scale i ask my colleages of the same role as i am.

I usually try to compartmentalize it into areas of concern, like little bubbles/areas that can be individually studied and familiarized with, even though they all connect to other areas later.

As an example, I most often work in the frontend, so that means starting with the GUI and what a user sees (the overall flow of the app, maybe the UX design system and patterns). Then looking behind the scenes, it takes a couple days to understand the big-picture architecture (frameworks used, events and state management, routing, logging, fetching, etc. and how all those pieces are connected).

Once I get access to the actual repos (in the first week or so), I start to look for all those pieces that were previously described to me, and go through them line by line (or at least file by file, at a detailed skim) to both verify what I was told and to see what coding practices (standards or otherwise) may be in place. During this time, I'm usually in a "learn and copy" mode, not questioning the whys or hows yet, just noting down what was done previously. My first few PRs are simple bug fixes following the same styles and guidelines, fixing low-hanging fruit issues that are easily reviewed and not controversial in any way.

This is also when I spend a lot of time diving into the existing documentation, verifying what I can and updating what is obviously wrong with the most current information. It both helps me, as a new dev, and hopefully helps other newcomers in the future too. And the documentation often includes a lot of the "whys" that aren't obvious in the code.

Then, from there it usually takes me several months of working deep inside the codebase day-to-day to start to discover the "gotchas" -- both intentional tradeoffs and mistakes or minefields left by previous devs. The real bulk of my job is working around those issues, improving them where there's a clear cost-benefit to doing so, or backlogging/"won't do"ing them where there's not, while still delivering user-facing features and bugfixes. Often there isn't a budget set aside specifically for refactoring and tech debt (or if there is, it's the lowest priority and the first to get cut), so I just try to wrap that into my other work (like at a 20% markup or whatever).

Once in a while I'll scream about some particular issue, like, "This is a big deal, not just everyday tech debt. It's a security/privacy/performance/maintainability nightmare that we really need to set aside a sprint to fix". But you don't get to play that card all the time, so use it sparingly and only when something is actually a big deal.

Eventually, after a half year or so and with sufficient mastery of the existing systems, I'm usually in a position to propose re-architecting some parts of the system that are either unnecessarily convoluted or just a poor fit for the actual way our devs work. Normally this just means swapping out some commercial off-the-shelf subsystem with something that's similar but different enough, or less complex while still meeting our needs. Rarely do I try to reinvent the wheel and write my own architecture from scratch.

But anyway, this half-year mark is also usually when I feel confident enough in my own sphere of influence that I start interfacing with other teams to learn about their parts of the stack, working together to investigate things like performance bottlenecks, cross-domain bugs, datetime & timezone issues, user journey logging & end-to-end debugging, maybe basic DB, microservices, cloud vendors, etc. architectures and how they all fit together (or not, as is often the case in small-biz spaghetti setups).

At about a year in, I'm usually familiar enough with the different systems at play that my opinion is valued, but not authoritative. There will always be individuals with better knowledge of a given subsystem, but it's not my job to know that system better than them. I just need to understand how it interacts with my systems (at a detailed level) and other systems overall (at a shallow level). Then we work together to solve issues both preemptively, when we're smart enough, or through testing or user feedback.

Around this time is also when people tend to stop either worrying that you're too new, or concerned that you're not good enough (you probably would've left the team/company by then if you can't perform at a basic level). You're just another member of the team by this point, and you're approaching problems together because nobody knows all of it and we all need each other's help.

By that point, the problems you end up tackling are those that are non-trivial enough to require cross-team input from several devs anyway. Those are the fun projects! And everybody's on relatively equal footing by then. Maybe there's a senior or a lead or two in the mix, but they don't unilaterally make the calls. A good one will listen to different perspectives from all the individuals involved and come up with some solution that satisfies the most important criteria without pissing anyone off.

That's the frontend experience of the last few years for me. But back when I worked full-stack, it was still similar... start with some small sphere of concern, learn it well, learn its neighbors, expand outwards, eventually start working with people from different backgrounds and together solve problems that affect everyone.

IMO, there's nothing wrong with taking a few weeks to learn the basics, and a few months to get good at them. Maybe I've just been a part of good enough organizational cultures that valued high-quality output and thoughtful design/architecture over rushed code, but it's usually been a positive experience for me to push back on unrealistic deadlines or rush jobs because they always come back to bite the whole company, not just me or my team, later on. Hopefully your managers are receptive to such feedback (if not, I'd argue it's a sign to find another position or company ASAP).