Initial Codebase Exploration

Started by reading the codebasess Claude.md

Did not understand, piviting to researching on how to best go about this.

Read how to learn new codebases first

Had some good points, namely: - The best way to get started is to work with the code itself. - Understand the why behind archetecutural decisions (Best to ask Reghardt when I have questions about this) - Create personal documentation... hmm - Gather domain information - Build a technical maps. (Really like this one)

Did not have much actionalable suggestions, turned to reddit.

Some useful responses:

• "Pick an entry point and walk the call stack until you’ve got a working model of the whole thing in your head."
• "for me I start with learning the business logic/domain first. Once I know what's the expected behaviour, knowing the implementation details such as syntax becomes less taxing. Looking at existing tests if there are any also helps"
• "Find the edge points, be that networking. File io, db. Logging, entrypoints, etc. Then familiarize yourself with each one at a time. Then look at utility functions. These individually don't actually make the whole system make sense, but they start to lay the bricks to help you build a foundation of knowledge. If s module or feature isn't documented, then if they have a task to document it. Then do it. Worse case you are wrong and get corrected in PR comments, but best case you are wrong and get corrected in PR comments. And then you have contributed to the project and learned more about the system."
• "My approach is usually to pick old bugs off the backlog that have been sitting for a while. Figuring out how to reproduce them helps me learn the UI/UX. Figuring out how to fix them will force me to learn not only the codebase, but also the tooling. Some of the other suggestions here that boil down to “read the code” just don’t work for me. I need practical hands-on things to do otherwise I’m wasting my time."

I'll just follow the last one, tracks with Doug's advice about finding something small in triage and working on it.

But first i'll break down the CLAUDE.md file

Run Program -> bin/dev Test -> bin/rails test

Respec -> TDD Testing Framework for Ruby

The "core advisory workflow" seems to have special tests to make sure it does not break (makes sense because if that breaks no one can use the software)

Dev and Prod branch.

Stack

• Ruby on Rails, PostGIS
• PostGIS + activerecord-postgis-adapter
• Importmap -> In lieu of a bundler, the html is sent with a map which maps js import paths with file paths to pull the js files from.
• Hotwired (Just Turbo and Stimulus)-> SSR framwork
• Tailwindcss
• Sidekiq -> Apparently for bacground jobs and cron
• Devise -> Devise authenticatates and Pundit Authorizes. Pretty Simple.
• Active Storage -> Makes it easy to reference a files stored in a database, actual data is stored in cloudflare R2
• Redis -> Redis
• Mapbox GL Js -> Map Library

There was a lot of information, a lot I deemed unecessary to understand and take note of right now. I think the best thing I can do over the next few days is to start on an easy issue and create a small rails app with the same stack to gain more intuitive understanding of how all peices fit together.

Stoped looking into the codebase, learned more ruby syntax. While doing so I asked claude how I can best learn the codebase and it suggested the following:

1. Ruby basics (1–2 days) — Ruby in 100 Minutes or The Well-Grounded Rubyist. Focus on blocks, symbols, hashes, classes, modules.
2. Rails fundamentals (3–5 days) — the official Getting Started with Rails guide. Understand MVC, routes, ActiveRecord, and migrations before touching the codebase.
3. Read this app's routes — bin/rails routes | less to get a map of every URL → controller → action.
4. Trace one request end-to-end — pick something simple like viewing a MapFeature and follow it through route → controller → model → view.
5. Read the models — start with MapFeature, FieldNote, Team. ActiveRecord associations tell you the data relationships.
6. Then tackle the harder parts — Pundit authorization, Turbo/Stimulus, Sidekiq jobs, the Claude AI pipeline.

Avoid starting with the frontend JS, the API v3 mobile layer, or PostGIS — those are advanced.

Seems way more actionable and useful compared to the article and reddit comments.