BestBuds Architecture Refactor Plan

Decision

BestBuds should be refactored around a small set of powerful concepts: graph, route, interactor, actor, repository, service, screen state, and scoped design component. Screens should be declarative and readable. Interactors should own data plus actions. Actors should own focused asynchronous loops and state machines. The design module should expose a proper atomic hierarchy without BB* wrapper compatibility shims.

Current Shape

The app has already moved a long way from the legacy frontend. The remaining issue is not lack of components; it is mixed abstraction levels. Some screens still combine graph payloads, repository calls, data shaping, analytics, mutable local workflow state, layout, and low-level visual details in the same file. Some components are well-scoped; others are just moved elsewhere, which creates ravioli code instead of declarative UI.

Target Model

The target structure is a graph-backed UI architecture where each layer has a precise reason to exist. The goal is not ceremony. The goal is that a small number of concepts can express a large product surface without duplicating logic or leaking implementation details upward.

Atomic Design

Atomic design gives us a vocabulary for moving between parts and whole without losing either. Brad Frost's model uses atoms, molecules, organisms, templates, and pages. For BestBuds, the names should be adapted to Compose and product code, but the hierarchy should remain strict.

React/Actor Philosophy

The product should follow the same mental model that makes React and actor systems powerful: a small number of composable primitives, explicit state, clear message flow, and local reasoning. The implementation should not grow new concepts unless they generalize across real use cases.

What this means in code

• A screen should call interactor.actions.send(), not assemble service payloads.
• A screen should render state.timeline, not fetch, merge, sort, and annotate messages.
• A component should render a ConversationSummaryUi, not inspect raw service DTOs.
• An actor should expose a focused state flow and action surface, not a broad utility object.
• New primitives must serve multiple domains or be clearly local to one feature.

Graph Ownership

Reaktor's graph model should be the backbone of the app, not just a navigation wrapper. BestBuds should use graph nodes to make lifecycle and ownership explicit: services and repositories are providers, interactors are product capability nodes, actors are owned by interactors or narrow graph nodes, and screens consume only the state/actions they need.

Screen Inventory

The current UI is visually stronger than before, but data and action ownership varies by screen. The refactor should be comprehensive and staged by product flow risk.

Domain Interactors

Interactors should become the product API used by screens. The intent is not to make every action global. The intent is that each domain has one obvious place where data, actions, analytics, cache invalidation, optimistic updates, and navigation-safe product decisions live.

UI Layering

The design module should keep moving toward a real atomic library. App screens should consume semantic organisms and screen blocks, while still showing enough structure to be readable. The themed {} scope should be the primary way to access theme-aware components.

Scope facets

BestBudsThemeScope can be powerful without becoming a single huge interface. Prefer capability facets installed into the themed scope:

• SurfaceComponents: card, panel, sheet, backdrop, separators.
• TextComponents: headings, body copy, captions, labels, metadata.
• InputComponents: text fields, search, composer input, segmented controls, chips.
• IdentityComponents: avatars, stacks, identity rows, verification marks.
• FeedComponents: list sections, empty states, loading states, row containers.
• ActionComponents: buttons, icon actions, floating actions, menus, action rows.
• MotionComponents: transitions, press feedback, reveal, shimmer, scroll effects.

Component Rules

Component extraction should make the code more expressive. It should never hide the screen's structure or create a thin wrapper around a primitive just to add a prefix.

Examples

These examples show the target level of abstraction. They are not final code, but they define the shape of the refactor.

Chat list screen after refactor

@Composable
override fun Content() = themed {
    TrackScreenView("chat_list")
    val state by chatListInteractor.state.collectAsState()

    ScreenColumn(
        contentPadding = ScreenPadding.feed,
        verticalSpacing = Spacing.small,
    ) {
        item { ChatListHero(state.hero) }
        item {
            ConversationFilters(
                filters = state.filters,
                selected = state.selectedFilter,
                onSelect = chatListInteractor::selectFilter,
            )
        }

        conversationSections(
            sections = state.sections,
            onOpen = { chatListInteractor.open(it) },
        )
    }
}

The screen still shows the visual skeleton. What changed is that counts, filters, pinned logic, unread logic, sticker hydration, analytics, and route-safe open behavior moved to ChatListInteractor.

Chat session ownership

class ChatSessionInteractor(
    private val timeline: MessageTimelineActor,
    private val socket: ChatSocketActor,
    private val composer: ComposerActor,
    private val reactions: ReactionActor,
    private val forwarding: ForwardingActor,
) : BasicNode(...) {
    val state: StateFlow<ChatScreenState> = combine(...)

    fun open(payload: ChatPayload)
    fun close()
    fun retry(messageId: String)
    fun react(messageId: String, reaction: Reaction)
    fun showGroupProfile()
}

The parent interactor composes actors. It does not become a second god object. Each actor owns a single workflow, and ChatScreenState is the product-facing shape consumed by Compose.

Profile screen after refactor

@Composable
override fun Content() = themed {
    val state by profileInteractor.state.collectAsState()

    ScreenColumn(contentPadding = ScreenPadding.feed) {
        item { ProfileHero(state.identity, onPhoto = profileInteractor::changePhoto) }
        item { ProfilePromptEditor(state.prompts, profileInteractor.prompts) }
        item { ProfilePrivacyPanel(state.privacy, profileInteractor.privacy) }
        item { ProfileSessionActions(state.session, profileInteractor.sessionActions) }
    }
}

This is the target: a reader can see the profile page structure without reading field plumbing, dirty-state logic, geolocation side effects, or save/retry behavior.

File Plan

Most files should stay under roughly 500 lines. The exception is a topology file like BestBuds.kt, where length is acceptable if it lets the app graph be read in one place. The file boundary should follow ownership, not arbitrary line count.

Migration Phases

The refactor should be done in vertical slices that preserve behavior after each step. The chat domain should move first because it has the most state and the highest market impact.

Definition Of Done

The migration is finished only when the real BestBuds apps are migrated, not when the documentation is complete.

Guardrails

• Do not add primitives for one use case. A primitive must generalize or stay private.
• Do not use "template" as a way to hide an entire screen elsewhere.
• Do not over-normalize incompatible components into one interface.
• Do not move business logic into design components.
• Do not create graph nodes that only rename an existing service or repository.
• Do not degrade the readability of BestBuds.kt; it should remain the app topology map.
• Do not block real app migration on docs or speculative architecture work.
• Keep the prototype and appWeb as visual references, but app code should have native ownership and state models.

Next Implementation Order

This is the recommended next sequence for actual code work after this document.

1. Create a small screen-state/action pattern and register ChatListInteractor.
2. Move chat list filtering, pinned/unread sections, sticker hydration, analytics, and open-chat routing into ChatListInteractor.
3. Split ChatInteractor into ChatSessionInteractor plus socket, timeline, composer, reactions, forwarding, and typing/presence actors.
4. Refactor ChatScreen to render ChatScreenState while preserving the screen's top-level visual skeleton.
5. Repeat the same pattern for onboarding, profile, events, campaigns, discover, and friends.
6. Reorganize the design module into atomic folders and scoped component facets once app usage proves the right boundaries.
7. Run Android and iOS Maestro smoke flows after each vertical slice, then the full suite at the end.

Sources

• Local scan of /Users/ovd/dev/bestbuds/modules/app/src/commonMain/kotlin/ai/bestbuds/app.
• Local scan of /Users/ovd/dev/bestbuds/modules/design/src/commonMain/kotlin/ai/bestbuds/design.
• Atomic Design table of contents and Atomic Design Methodology by Brad Frost.