Current architecture
Second Thought’s current architecture is built on ports and adapters, around a pure core.
Frontends
There are two frontends with the same functionality: the CLI and the VS Code extension.
Each one creates the LLM client and the passes, calls review(), and shows the result to the user:
the CLI as text in the terminal, the extension as underlines and quick fixes.
Core
review() is the Context of the Strategy pattern and holds the core business logic. Its input is an article.
It runs the passes, then applies the system-wide rules: it drops every suggestion that touches a protected range
(this is the guard), stops early on systemic LLM errors (fail-fast), and builds the diff.
Passes
Each pass has its own system prompt. It gets the prose from the Segmenter, sends it to the LLM through the
LlmClient interface, and turns the reply into findings. The language pass also narrows each fix to the words
that actually changed.
Port and adapter
LlmClient is the port: the core only knows this interface, not the provider. The Gemini adapter implements it:
it talks to Gemini over HTTPS, retries on 429 and network errors, and translates the provider’s errors into our own
error kinds, so the raw response never crosses the port.
Planned architecture
When I made the current architecture diagram for the project page, I noticed some weaknesses:
- Parsing happens multiple times (in the review and in the passes). This is not efficient.
- The frontends know about the exact LLM client. This makes the architecture inflexible.
So I started to plan the next architecture.
Review module plan
In the next version I plan to make a separate module for the review, the passes and their elements. I would like to make one bigger module. It would be a bit monolithic, but in this phase of the project I think it is acceptable. The module would make the architecture more flexible, and it would hide the exact LLM from the frontends. I haven’t decided yet whether I will use an API or keep the review as a strategy.
Technical Fact Check Pass
I also plan a new pass to check the technical facts. It would be an element with explanations, source links and proof of truth. This will be a new functionality to help me check whether my articles are correct enough.
Application architecture
With the new module, I think it will be easier to attach new UIs. I also plan a preprocessor that would, for example, create the segments and run a traditional language check.
Swift application
I plan a Swift application for the project. It would run the same TypeScript core as a sidecar binary, so I don’t have to rewrite the review logic in Swift.
Output provider
A planned output provider would make the diffs and maybe the format for the frontends.


