Streamlining Your Codebase: A Guide To Folder Organization

by Admin 59 views
Streamlining Your Codebase: A Guide to Folder OrganizationIt's time to talk about something crucial that often gets overlooked in the hustle of development: *codebase organization*. Hey guys, ever felt lost in a sea of files, scrolling endlessly through a giant `hooks` or `components` folder? You're not alone! Many of us face this challenge, especially in growing projects like `genesis-ai-dev` and `langquest` where functionality expands rapidly. A flat, sprawling folder structure can quickly become a developer's worst nightmare, making it *incredibly difficult* to find what you need, understand existing code, or onboard new team members. This isn't just about aesthetics; it's about **efficiency, maintainability, and scalability**. When your codebase isn't properly structured, development slows down, bugs become harder to track, and the sheer cognitive load on engineers skyrockets. Imagine trying to build a complex, innovative AI-driven language learning platform with a messy blueprint – it's just not going to work smoothly.That's why we're diving deep into refactoring and reorganizing our core folders: `hooks`, `components`, and `utils`. Our goal here is to create a more intuitive, domain-driven structure that reflects how we actually think about and use our code. We want to move away from generic, overflowing directories and embrace a system where every file has a clear home and purpose. Think about it: a well-organized workspace makes you more productive, right? The same applies to your code. This isn't about arbitrary categorization; it's about making our development lives easier, fostering a clearer understanding of the project's architecture, and setting ourselves up for long-term success. We're talking about reducing friction, improving discoverability, and ultimately, accelerating our ability to deliver amazing features to our users. So, let's roll up our sleeves and transform our codebase from a cluttered attic into a well-curated library, making it a joy to work in for everyone involved. No more `New` folders or `NextGen` files lingering indefinitely; we're building for clarity and precision, ensuring our powerful `genesis-ai-dev` and `langquest` applications have a rock-solid, understandable foundation. We're going to make our code *work for us*, not against us, by thoughtfully structuring every piece to boost our collective productivity and enjoyment. This is an investment in our future development, guaranteeing that as our project evolves, our codebase remains a source of clarity and not confusion. We're establishing conventions that will guide us for years to come, making it simpler to collaborate, debug, and innovate. This strategic refactor will not only clean up our directories but also embed a clearer architectural philosophy into our project, benefiting every developer who touches the code. It's about designing a system that scales gracefully and remains intuitive, even as complexity grows, ensuring that the development experience stays pleasant and productive for the entire team. This thoughtful approach ensures that our powerful tools and features are built upon a foundation that is as robust and well-organized as the ideas they embody. We're setting new standards for ourselves, moving towards a development environment where every file has a precise, logical home, making it effortless to navigate, contribute, and maintain. This is more than just tidying up; it's about optimizing our entire workflow for maximum efficiency and clarity. By addressing these foundational elements, we empower ourselves to build more, innovate faster, and collaborate seamlessly, ensuring our projects not only meet but exceed expectations. This effort will ultimately elevate our development process, allowing us to focus more on creating value and less on deciphering a disorganized directory. It's an investment in a cleaner, more efficient, and ultimately more enjoyable coding experience for everyone on the team, solidifying our path toward continued success and innovation in `genesis-ai-dev` and `langquest`. We are making a conscious decision to prioritize architectural integrity, which will pay dividends in the long run by significantly reducing technical debt and increasing our agility. It's a proactive step to ensure that as our applications become more sophisticated, their underlying structure remains simple, elegant, and easy to manage. This foundational work will empower us to innovate with greater confidence and speed, knowing that our codebase is a solid and reliable asset, not a burden. By adopting these organizational principles, we're not just moving files; we're cultivating a culture of precision and clarity within our development practices, which is essential for any high-performing team. This commitment to structure ensures that future development remains swift and predictable, turning what could be a chaotic growth into a well-managed expansion. We’re laying down the groundwork for a truly scalable and maintainable system, directly contributing to the long-term health and success of our projects. This isn't just a one-time cleanup; it's about establishing sustainable practices that will serve our team well into the future. Each decision in this refactor is geared towards fostering a more intuitive and resilient architecture, allowing us to focus on what truly matters: delivering exceptional features and user experiences. We're building a foundation that is designed to grow with us, ensuring that our codebase remains a clean, efficient, and welcoming environment for all contributors, both new and old. This strategic move is about more than just rearranging files; it's about instilling a disciplined approach to development that will minimize friction and maximize productivity. By investing in this structural improvement, we're making a strong statement about our commitment to quality, efficiency, and collaborative excellence, ensuring that our `genesis-ai-dev` and `langquest` projects continue to thrive on a solid, well-organized base. The resulting clarity will empower developers to understand complex logic faster, reducing the learning curve for new team members and accelerating feature implementation across the board. This proactive approach to *codebase organization* will translate directly into a more agile and responsive development cycle, allowing us to adapt quickly to new requirements and maintain a competitive edge. Ultimately, this refactoring effort is about future-proofing our applications, ensuring they can evolve and scale without succumbing to the common pitfalls of technical debt and disorganization. We’re building a legacy of clean code that fosters innovation and collaboration, setting a new standard for development within our team. This commitment to a well-structured codebase is a cornerstone of our success, providing the stable foundation needed to push the boundaries of AI-driven language development. It’s about creating an environment where developers can truly excel, free from the distractions of a chaotic file system, allowing them to channel their energy into creative problem-solving and delivering high-impact features. This is a significant step forward in our journey to build world-class applications, driven by a philosophy of clarity, efficiency, and continuous improvement. We are designing for longevity, ensuring that our codebase remains a lean, mean, feature-shipping machine, ready to tackle any challenge that comes our way. By embracing these principles of meticulous organization, we are not just improving our code; we are enhancing our entire development culture, paving the way for sustained innovation and team synergy. This is the path to building not just good software, but *great* software, where every line of code contributes to a harmonious and efficient whole. It's about empowering our team to do their best work, confidently, efficiently, and joyfully, knowing that the underlying structure supports their every endeavor. We're creating a development environment that nurtures creativity and problem-solving, making the act of coding a more satisfying and productive experience for everyone involved. This strategic reorganization is a testament to our dedication to excellence, ensuring that our `genesis-ai-dev` and `langquest` projects remain at the forefront of technological innovation, backed by an impeccably organized and highly functional codebase. It’s a game-changer, folks, seriously! It's about making our lives as developers a whole lot easier and more enjoyable. Let's make this happen!## Supercharging Your Hooks: A Clean Structure for Clarity and PerformanceAlright, let's kick things off with our `hooks` folder – a place that often becomes a treasure trove of reusable logic, but also, let's be honest, can quickly turn into a messy attic if left unchecked. When you have dozens, or even hundreds, of hooks all sitting at the top level, finding `useMySpecificDataQuery.ts` amidst `useSomeUIState.ts` and `useMicrophoneEnergy.ts` becomes a true test of patience. This *flat structure* creates a huge cognitive load; every time you open the `hooks` directory, your brain has to parse an overwhelming list of files. This not only slows down development as you waste precious minutes searching, but it also increases the likelihood of creating duplicate logic or misusing existing hooks because their purpose isn't immediately clear. For a complex platform like `langquest`, where we're juggling database interactions, real-time syncing, audio processing, and intricate UI states, a disorganized `hooks` folder can be a serious bottleneck, hindering our ability to rapidly develop new features and maintain existing ones.Imagine trying to debug an issue related to data synchronization when all sync-related hooks are scattered across a giant folder, interspersed with UI-specific or analytics-related hooks. It's like finding a needle in a haystack, except the haystack is constantly growing! This is why *structuring our hooks thoughtfully* is not just a nice-to-have; it's a fundamental requirement for **scalability and maintainability**. Our goal here is to transform this critical directory into a well-organized library where every hook's purpose and domain are immediately apparent, making it a joy to navigate and utilize. We're moving towards a **domain-driven design** within our hooks, categorizing them by the specific areas of functionality they address. This approach isn't just about grouping files; it's about creating logical boundaries that reduce coupling, improve discoverability, and make our codebase far more understandable. When you're working on a new feature that requires, say, audio recording, you'll know exactly where to look for relevant hooks without sifting through unrelated logic. This clarity significantly **reduces onboarding time** for new developers, allowing them to quickly grasp the architecture and contribute effectively. It also makes code reviews more straightforward, as the context for each hook is naturally encapsulated within its dedicated folder. Furthermore, a well-defined structure helps prevent naming collisions and encourages consistency across the team. By explicitly defining areas like `sync/`, `bible/`, `media/`, and `queries/`, we create a shared vocabulary around our application's concerns, which fosters better communication and collaboration. This refactor is an investment in our collective productivity, ensuring that our `genesis-ai-dev` and `langquest` projects can continue to evolve at a rapid pace, supported by a codebase that is as intuitive as it is powerful. We're setting ourselves up for success by making our `hooks` directory a model of clarity and efficiency, enabling developers to build faster, debug smarter, and innovate with greater confidence. This structural overhaul is designed to eliminate friction points, allowing our team to focus more on creative problem-solving and less on organizational overhead. It’s about building a sustainable and scalable foundation, ensuring that as our application grows in complexity, our ability to manage and enhance it grows alongside. This thoughtful approach transforms our hooks from a potential source of chaos into a powerful, well-indexed toolkit, ready for any challenge. We’re creating a development experience where every hook has its precise place, making it effortless to locate, understand, and reuse, ultimately boosting our overall development velocity.### Proposed Structure for Hooks```texthooks/├── db/ # ✅ Already exists - entity CRUD hooks│ └── (keep as-is: useAssets, useBlocks, useLanguages, etc.)│├── utils/ # Generic utility hooks│ ├── use-debounced-callback.ts│ ├── use-debounced-memo.ts│ ├── use-debounced-state.ts│ └── useDeferredQuery.ts│├── sync/ # Offline-first, sync, download, network│ ├── useNetworkStatus.ts│ ├── useSyncState.ts│ ├── usePowerSyncStatus.ts│ ├── useHybridQuery.ts│ ├── useHybridSupabaseQuery.ts│ ├── useDownloads.ts│ ├── useAssetDownloadStatus.ts│ ├── useQuestDownloadDiscovery.ts│ ├── useQuestDownloadStatusLive.ts│ └── useQuestOffloadVerification.ts│├── bible/ # Bible/chapter-specific business logic│ ├── useBibleBookCreation.ts│ ├── useBibleChapterCreation.ts│ ├── useBibleChapters.ts│ ├── useChapterExport.ts│ └── useChapterPublishing.ts│├── media/ # Audio, attachments, microphone│ ├── useMicrophoneEnergy.ts│ ├── useMicrophoneEnergy.web.ts│ ├── useHaptic.ts│ ├── useAttachmentProgress.ts│ └── useAttachmentStates.ts│├── ui/ # Navigation, theming, localization│ ├── useAppNavigation.ts│ ├── useColorScheme.tsx│ └── useLocalization.ts│├── analytics/ # Analytics, profiling, dev tools│ ├── usePostHog.ts│ ├── usePostHog.web.ts│ ├── useProfiler.ts│ ├── useDrizzleStudio.noop.ts│ ├── useDrizzleStudio.tsx│ └── useDrizzleStudio.web.tsx│├── queries/ # Business logic data queries│ ├── useLanguagesByRegion.ts│ ├── useNearbyTranslations.ts│ ├── useProjectsByLanguage.ts│ ├── useRegions.ts│ ├── useReports.ts│ ├── useTranslationPrediction.ts│ ├── useTranslationReports.ts│ ├── useBlockedCount.ts│ ├── useQuestPublishStatus.ts│ └── useUserPermissions.ts│├── platform/ # Platform-specific hooks│ ├── useExpoUpdates.ts│ ├── useExpoUpdates.mock.ts│ └── useNotifications.ts│└── index.ts # Re-export all hooks```### The `db/` Folder: Your Entity CRUD PowerhouseThis folder, thankfully, is *already well-organized*, which is a huge win! The `db/` folder in our hooks is specifically designed for **direct entity CRUD operations**. Think of it as the direct interface to our database entities – managing assets, blocks, languages, and so on. It's where you'll find hooks that handle the basic *create, read, update, and delete* functionalities for our core data models. Keeping this folder focused purely on these foundational database interactions ensures that our data layer remains consistent and predictable. This separation means that any developer looking to interact with a specific database entity knows exactly where to find the corresponding hooks. It significantly reduces the mental overhead of tracking down data manipulation logic, making our interactions with `PowerSync` and other data sources clear and efficient. This focus also helps to enforce a clean architecture, distinguishing raw data operations from more complex business logic queries or UI-specific state management. So, we'll keep `db/` as-is, leveraging its existing clarity.### The `utils/` Folder: Generic Utility HooksThe `utils/` folder is designated for **generic, reusable utility hooks** that have *no domain-specific knowledge*. These are the workhorses that can be applied across various parts of our application without being tied to a specific feature like Bible translation or media handling. We're talking about hooks like `use-debounced-callback.ts`, `use-debounced-memo.ts`, `use-debounced-state.ts`, and `useDeferredQuery.ts`. These hooks provide fundamental functionalities such as optimizing performance by debouncing frequent calls or managing asynchronous data fetching more gracefully. They are the essential building blocks that enhance user experience and application responsiveness by preventing unnecessary re-renders or API calls. By centralizing these generic utilities, we ensure consistency across the codebase, reduce code duplication, and make our application more robust. This folder is all about providing foundational, universally applicable tools that any part of the app can benefit from, making our development process smoother and more efficient.### The `sync/` Folder: Offline-First, Sync, Download, NetworkThis is a *critical* folder, especially for an application like `langquest` that heavily relies on **offline-first capabilities and robust data synchronization**. The `sync/` folder will house *everything* related to managing our offline data, network status, data syncing processes, and downloads. Hooks such as `useNetworkStatus.ts`, `useSyncState.ts`, `usePowerSyncStatus.ts`, `useHybridQuery.ts`, and `useDownloads.ts` are perfect fits here. This includes tracking connectivity, managing the state of our PowerSync synchronization engine, and handling the complex logic involved in downloading and offloading assets and quests. By grouping these together, we create a clear, dedicated space for all the intricate logic that ensures our users have a seamless experience, whether they are online or offline. This organization is vital for debugging and understanding the flow of data, as all related mechanisms are consolidated. It highlights the importance of our hybrid data architecture, making it easy for developers to interact with and enhance the synchronization layer. When you need to understand how data moves between local storage and the cloud, or how downloads are managed, `sync/` will be your first stop, providing a holistic view of these essential offline-first capabilities.### The `bible/` Folder: Bible/Chapter-Specific Business LogicFor `langquest`, the Bible translation workflow is a core domain, so a dedicated `bible/` folder for **Bible/chapter-specific business logic hooks** makes perfect sense. This is where you'll find hooks like `useBibleBookCreation.ts`, `useBibleChapterCreation.ts`, `useBibleChapters.ts`, `useChapterExport.ts`, and `useChapterPublishing.ts`. These hooks encapsulate the complex operations involved in creating, managing, exporting, and publishing Bible content. By isolating this domain logic, we ensure that changes or enhancements to the Bible translation process are contained within a specific, understandable part of the codebase. This clarity is invaluable for developers working on features directly related to content creation and dissemination, making it easier to reason about the flow and state of Bible data. It helps to keep our core domain logic distinct from generic utilities or UI components, thereby promoting a cleaner and more maintainable architecture. This folder becomes the definitive source for all hooks that drive the unique `langquest` Bible workflow, providing a clear roadmap for anyone engaging with this critical functionality.### The `media/` Folder: Audio, Attachments, MicrophoneOur application deals extensively with **audio, attachments, and microphone interactions**, making a `media/` folder absolutely essential. Here, we'll place hooks such as `useMicrophoneEnergy.ts` (and its web counterpart), `useHaptic.ts`, `useAttachmentProgress.ts`, and `useAttachmentStates.ts`. This folder consolidates all logic related to capturing, processing, and displaying media elements. Whether it's visualizing microphone input, providing haptic feedback for user interactions, or tracking the progress of file uploads and downloads, these hooks will reside here. This grouping ensures that all media-related functionalities are easily discoverable and consistently managed. It prevents media logic from being scattered across the codebase, making it simpler to implement new media features or debug existing ones. For a platform focused on language recording and translation, the `media/` folder is a cornerstone, providing a clear boundary for how we interact with and manage rich content. This dedicated space underscores the importance of media handling in our application, ensuring that its complexities are managed in a structured and accessible manner.### The `ui/` Folder: Navigation, Theming, LocalizationThe `ui/` folder for hooks is all about managing **UI state: navigation, theming, and internationalization (i18n)**. This is where you'd find `useAppNavigation.ts`, `useColorScheme.tsx`, and `useLocalization.ts`. These hooks are directly responsible for how our application *looks and feels* and how users *navigate* it. `useAppNavigation` centralizes routing logic, `useColorScheme` manages dark/light mode preferences, and `useLocalization` handles language and text translation across the user interface. By placing these UI-specific concerns together, we ensure that our application's presentation layer is consistently managed and easily adaptable. Any changes to the navigation flow, theme settings, or language support can be found and implemented efficiently from this centralized location. This separation helps to decouple UI presentation logic from core business logic, making the UI layer more modular and testable. It provides a clear domain for hooks that directly influence the user's interactive experience, ensuring a cohesive and responsive user interface across the application.### The `analytics/` Folder: Analytics, Profiling, Dev ToolsThe `analytics/` folder is dedicated to **tracking, profiling, and developer tools** hooks. This is where you'd find `usePostHog.ts` (and its web variant), `useProfiler.ts`, and the various `useDrizzleStudio.tsx` files. These hooks are crucial for understanding user behavior, monitoring application performance, and aiding in debugging during development. `usePostHog` facilitates event tracking and user analytics, providing insights into how our application is being used. `useProfiler` helps us identify performance bottlenecks, ensuring a smooth and responsive user experience. The `DrizzleStudio` hooks provide valuable development tooling for inspecting our database. Grouping these hooks together ensures that all instrumentation and diagnostic logic is centralized, making it easier to integrate new tracking features, analyze performance, or enable debugging tools. This separation also allows us to conditionally include or exclude these hooks based on the environment (e.g., development vs. production), optimizing bundle size and security. It creates a clear boundary for all non-functional requirements related to monitoring and diagnostics, underscoring our commitment to data-driven insights and application health.### The `queries/` Folder: Business Logic Data QueriesThe `queries/` folder is designed for **complex business logic queries that fetch or combine data but aren't simple CRUD operations**. Think of hooks that involve multiple database tables, intricate filtering, or data aggregation that goes beyond what's handled in `db/`. Examples include `useLanguagesByRegion.ts`, `useNearbyTranslations.ts`, `useProjectsByLanguage.ts`, `useRegions.ts`, `useReports.ts`, `useTranslationPrediction.ts`, `useTranslationReports.ts`, `useBlockedCount.ts`, `useQuestPublishStatus.ts`, and `useUserPermissions.ts`. These hooks often involve specific domain knowledge, combining data from various sources to provide a richer dataset for the UI. By placing them here, we differentiate them from basic CRUD operations, emphasizing their role in deriving meaningful insights or prepared data for specific features. This segregation helps in understanding the data flow and the business rules applied when fetching complex datasets. It promotes a clearer separation of concerns, ensuring that our data retrieval logic is well-organized and easy to maintain. These queries are the backbone of many dynamic features, and their consolidated placement makes them more accessible and manageable.### The `platform/` Folder: Platform-Specific HooksThe `platform/` folder is for **platform-specific features**. In a cross-platform application, certain functionalities might behave differently or be exclusive to a particular environment (e.g., web, native, Expo). Hooks like `useExpoUpdates.ts` (and its mock version) and `useNotifications.ts` are prime candidates for this directory. `useExpoUpdates` handles over-the-air updates for our native builds, while `useNotifications` manages push notifications and other platform-native alerts. Grouping these here ensures that all platform-dependent logic is isolated and clearly identified. This is crucial for managing conditional compilation and ensuring that platform-specific quirks are handled consistently. It also makes it easier to extend or modify platform features without affecting the core application logic. This folder acts as a bridge between our general application code and the unique capabilities or requirements of each target platform, providing a clean separation for these environment-dependent concerns.### Important Notes for Hooks Organization1. **`useReports.ts`**: The current root `useReports.ts` likely contains mutations and intricate business logic related to reporting and blocking, indicating it's more than just a simple CRUD operation. Therefore, it *belongs in `queries/`*. Conversely, if there were a `db/useReports.ts`, that would ideally be pure CRUD for a `Report` entity. This distinction is crucial for maintaining the integrity of our `db/` and `queries/` folders.2. **`useHybridQuery.ts`**: This hook is fundamentally about merging offline and online data, a core concept in our offline-first architecture. As such, it *definitely goes in `sync/`*. Its purpose is intrinsically tied to data synchronization and consistency across different network states.3. **`useUserPermissions.ts`**: This hook manages user access rights. While `queries/` is a suitable home, if we anticipate a growing number of authentication- or authorization-related hooks in the future, it might be worth creating an entirely new `auth/` folder. For now, `queries/` is fine, but keep `auth/` in mind as a potential future expansion.4. **Barrel Files (`index.ts`)**: Guys, *please consider adding an `index.ts` barrel file in each subfolder*. This makes imports much cleaner! Instead of `import { useFeature } from '../hooks/feature/useFeature'`, you can just `import { useFeature } from '../hooks/feature'`, which is much tidier and easier to manage as your codebase evolves. It reduces verbosity and improves the overall developer experience when importing modules from these newly organized directories.## Transforming Components: Building a UI Dream TeamOkay, let's switch gears and talk about our `components` folder – another area that can quickly become a dumping ground of UI elements, making it tough to build a *cohesive and maintainable user interface*. Just like our hooks, a flat `components` directory, brimming with everything from basic buttons to complex modals and entire screen layouts, creates massive headaches. When you have a single `components` folder with hundreds of files, it's a nightmare for discoverability. You spend more time searching for a `ProjectCard` than actually building with it. This lack of structure leads to inconsistencies, where similar UI elements might be implemented differently in various parts of the application because developers can't easily find or aren't aware of existing solutions. For `genesis-ai-dev` and `langquest`, where a consistent and intuitive user experience is paramount, this kind of disorganization directly impacts our ability to deliver high-quality UI. Moreover, a messy components folder makes **onboarding new team members significantly harder**. They have to mentally map out the entire UI structure from a flat list of files, which is a steep learning curve. Debugging visual glitches or refactoring UI elements becomes a daunting task, as the interdependencies and contexts of components are not immediately clear. This organizational challenge directly translates into slower development cycles, increased technical debt, and a higher risk of UI bugs. Our mission here is to transform our `components` directory into a *well-structured, intuitive design system* where every UI element has a logical home based on its type, domain, or specific purpose. We want to move towards a more modular and hierarchical structure, making it incredibly easy to find, understand, and reuse components. This approach isn't just about tidiness; it's about **empowering our developers** to build faster, more consistently, and with greater confidence. By segmenting components into logical categories like `modals/`, `audio/`, `project/`, and `skeletons/`, we create clear boundaries and reduce cognitive load. When you need a component for, say, displaying a quest, you know exactly where to look (`quest/`), rather than sifting through unrelated UI elements. This structured approach fosters **design system thinking**, encouraging the creation of reusable, composable components that adhere to a consistent visual language. It makes it easier to enforce UI/UX guidelines, ensure accessibility, and maintain a high level of polish across the entire application. Furthermore, it streamlines the process of styling and theming, as related components are grouped together. This refactor is a strategic move to boost our frontend development efficiency, reduce friction in UI development, and ultimately deliver a superior user experience for our `genesis-ai-dev` and `langquest` users. By investing in this component organization, we're building a solid foundation for a beautiful, responsive, and highly maintainable user interface that can scale gracefully with our ambitious product vision. We’re making our component library a joy to navigate, ensuring that our team can efficiently create stunning and functional interfaces without getting bogged down by organizational chaos. This thoughtful restructuring is all about empowering our designers and developers to collaborate more effectively, turning UI development into a streamlined, creative process rather than a frustrating search mission. We’re moving towards a system where every component serves a clear purpose within a well-defined architectural segment, enhancing both developer productivity and the overall quality of our user-facing product. This foundational work will reduce errors, speed up feature delivery, and allow us to maintain a consistent visual identity across all platforms and features.### Proposed Structure for Components```textcomponents/├── ui/ # ✅ Keep as-is - shadcn-style primitives│ └── (alert, badge, button, card, checkbox, drawer/, etc.)│├── navigation/ # ✅ Keep as-is│ └── TabBarIcon.tsx│├── icons/ # Custom icons│ ├── CalendarIcon.tsx│ ├── GemIcon.tsx│ ├── KeyboardIcon.tsx│ ├── LumpOfCoalIcon.tsx│ ├── MicrophoneIcon.tsx│ ├── PickaxeIcon.tsx│ ├── ThumbsUpIcon.tsx│ └── WaveformIcon.tsx│├── audio/ # Audio recording & playback│ ├── AudioPlayer.tsx│ ├── AudioRecorder.tsx│ ├── AudioSegmentItem.tsx│ ├── EnergyVADRecorder.tsx│ ├── MiniAudioPlayer.tsx│ ├── WalkieTalkieRecorder.tsx│ ├── WaveformVisualization.tsx│ └── WaveformVisualizer.tsx│├── modals/ # Modal dialogs│ ├── AssetFilterModal.tsx│ ├── AssetSettingsModal.tsx│ ├── AuthModal.tsx│ ├── DownloadConfirmationModal.tsx│ ├── ExportProgressModal.tsx│ ├── ModalDetails.tsx│ ├── NewReportModal.tsx│ ├── ProjectMembershipModal.tsx│ ├── ProjectSettingsModal.tsx│ ├── QuestFilterModal.tsx│ ├── QuestSettingsModal.tsx│ ├── ReportModal.tsx│ ├── TranslationSettingsModal.tsx│ └── VoteCommentModal.tsx│├── drawers/ # Bottom sheets / drawer panels│ ├── AppDrawer.tsx│ ├── DrawerLegendList.tsx│ ├── QuestDownloadDiscoveryDrawer.tsx│ └── QuestOffloadVerificationDrawer.tsx│├── skeletons/ # Loading skeletons│ ├── AssetListSkeleton.tsx│ ├── AssetSkeleton.tsx│ ├── LanguageListSkeleton.tsx│ ├── ProjectListSkeleton.tsx│ ├── ProjectSkeleton.tsx│ ├── QuestListSkeleton.tsx # move from questsComponents/│ └── QuestSkeleton.tsx # move from questsComponents/│├── layout/ # App shell & layout│ ├── App.tsx│ ├── AppHeader.tsx│ ├── AppUpgradeScreen.tsx│ ├── MigrationScreen.tsx│ ├── AccountDeletedOverlay.tsx│ ├── LoadingView.tsx│ └── PrivateAccessGate.tsx│├── project/ # Project-related components│ ├── ProjectDetails.tsx│ └── ProjectCard.tsx # (if exists)│├── quest/ # Quest-related components│ ├── QuestCard.tsx│ ├── QuestDetails.tsx│ ├── QuestItem.tsx # move from questsComponents/│ └── QuestsScreenStyles.tsx # move from questsComponents/│├── asset/ # Asset display components│ ├── SourceContent.tsx│ └── TranslationCard.tsx│├── language/ # Language selection│ ├── language-combobox.tsx│ ├── language-select.tsx│ └── LanguageSelect.tsx│├── input/ # Specialized input components│ ├── ArrayInsertionList.tsx│ ├── ArrayInsertionWheel.tsx│ ├── ArrayInsertionWheel.web.tsx│ ├── ArrayInsertionWheelContainer.tsx│ ├── InsertionCursor.tsx│ ├── CustomDropdown.tsx│ ├── PasswordInput.tsx│ ├── RadioSelect.tsx│ └── SwitchBox.tsx│├── carousel/ # Carousel & image display│ ├── Carousel.native.tsx│ ├── Carousel.tsx│ ├── Carousel.web.tsx│ └── ImageCarousel.tsx│├── progress/ # Progress indicators & counts│ ├── DownloadIndicator.tsx│ ├── IndeterminateProgressBar.tsx│ ├── OnboardingProgressIndicator.tsx│ ├── PendingCount.ts│ ├── PickaxeCount.tsx│ ├── ProgressBars.tsx│ └── SuccessCount.tsx│├── export/ # Export functionality│ ├── ExportButton.tsx│ └── ExportTypeSelector.tsx│├── dev/ # Development/debug tools│ ├── OTAUpdateDebugControls.tsx│ └── PerformanceDiagnostics.tsx│├── feedback/ # Banners, warnings, notifications│ ├── OfflineUndownloadWarning.tsx│ ├── UpdateBanner.tsx│ └── FloatingMenu.tsx│└── theme-toggle.tsx # Could stay at root or go in ui/```### The `ui/` Folder: Foundation of Our Design SystemThe `ui/` folder is our existing collection of **shadcn-style primitives**, and we're definitely keeping it as-is! This directory is home to fundamental, highly reusable UI elements like `alert`, `badge`, `button`, `card`, `checkbox`, and various drawer components. These are the *bedrock* of our design system – atomic components that form the visual and interactive foundation of our entire application. Keeping them consolidated and well-organized in `ui/` ensures **consistency across the application's look and feel**. Any developer needing a basic, styled UI element knows exactly where to find it. This approach promotes reusability, reduces development time, and makes it simpler to apply global styling changes or theme updates. It's crucial for maintaining a cohesive and polished user experience, ensuring that even the smallest UI elements adhere to our design guidelines. This folder embodies our commitment to a robust and scalable UI foundation.### The `navigation/` Folder: Streamlined App FlowThe `navigation/` folder, which we're also keeping as-is, typically contains components directly related to how users *move through* our application. For instance, `TabBarIcon.tsx` is a perfect example – it's a component specifically designed for rendering icons within a tab bar, guiding users through different sections of the app. While it might seem small, maintaining a dedicated `navigation/` folder is essential for centralizing navigation-specific UI elements. This separation makes it easier to manage routing logic, tab bar configurations, and other navigational components. It ensures that our app's flow is consistently represented and easily modifiable. When you're working on updating routes or changing the appearance of navigation elements, this folder provides a clear and focused place to make those changes, reducing the risk of unintended side effects on other parts of the UI. It plays a crucial role in delivering an intuitive and seamless user journey, making the application easy to explore and use.### The `icons/` Folder: Custom Visual AssetsOur `icons/` folder is where we'll house all of our **custom SVG/icon components**, keeping them separate from external libraries like `lucide-react-native`. This includes unique icons such as `CalendarIcon.tsx`, `GemIcon.tsx`, `KeyboardIcon.tsx`, `MicrophoneIcon.tsx`, and `WaveformIcon.tsx`. By centralizing our custom icons, we ensure a consistent visual language across the application and make it easy to manage, update, or add new bespoke icons. This separation prevents clutter in other component directories and clarifies where design assets are stored. It allows for better version control of our visual assets and simplifies the process of integrating new iconography without affecting the core UI primitives. This folder becomes the definitive source for any custom graphical elements, ensuring that our application's unique visual identity is consistently maintained and easily accessible to all developers and designers.### The `audio/` Folder: Audio Recording & PlaybackThe `audio/` folder is a powerhouse for `langquest`, dedicated to *all components related to audio recording, playback, and visualization*. Here, you'll find `AudioPlayer.tsx`, `AudioRecorder.tsx`, `AudioSegmentItem.tsx`, `EnergyVADRecorder.tsx`, `MiniAudioPlayer.tsx`, `WalkieTalkieRecorder.tsx`, `WaveformVisualization.tsx`, and `WaveformVisualizer.tsx`. This grouping is critical for an application heavily reliant on voice and sound. It brings together all the UI components that enable users to record their voice, play back audio, and visually interact with sound waves. By consolidating these, we make it incredibly easy to manage, debug, and enhance our audio functionalities. This ensures a consistent and high-quality audio experience across the application, from language practice to translation review. This folder is a central hub for our rich media interactions, providing a clear boundary for components that handle sound data and its user-facing representations.### The `modals/` Folder: Engaging Dialog OverlaysThe `modals/` folder will contain *all modal dialogs* – those interactive overlays that demand user attention and action. This includes components like `AssetFilterModal.tsx`, `AuthModal.tsx`, `DownloadConfirmationModal.tsx`, `ExportProgressModal.tsx`, `NewReportModal.tsx`, and `ProjectSettingsModal.tsx`. By centralizing all modal components, we ensure a consistent presentation and behavior for these crucial interaction patterns. This makes it easier to manage their state, apply uniform styling, and handle user input across various modal types. When a user needs to confirm an action, adjust settings, or fill out a form that requires a focused interaction, the relevant modal component will reside here. This organization helps in building a predictable and user-friendly interface, as developers know exactly where to create or find components for these specific types of dialogs. It reduces clutter in other folders and provides a clear separation for these often-complex, transient UI elements.### The `drawers/` Folder: Accessible Side PanelsOur `drawers/` folder is specifically for **bottom sheets and slide-out panels**, which offer a different, often less interruptive, way to present information or options than full-screen modals. Components like `AppDrawer.tsx`, `DrawerLegendList.tsx`, `QuestDownloadDiscoveryDrawer.tsx`, and `QuestOffloadVerificationDrawer.tsx` belong here. This separation distinguishes drawers from modals, as they often serve different UI/UX purposes – drawers might offer contextual information or a secondary navigation, while modals typically require more direct action. Grouping them ensures consistency in how these panels are implemented and styled, enhancing the overall fluidity of the user interface. It makes it easier to manage their opening/closing logic and animations, contributing to a smoother and more accessible user experience. This folder provides a dedicated space for these versatile panels, ensuring their coherent design and functionality throughout the application.### The `skeletons/` Folder: Graceful Loading StatesThe `skeletons/` folder is dedicated to **all loading placeholder components**. This is where we'll consolidate components like `AssetListSkeleton.tsx`, `ProjectListSkeleton.tsx`, `QuestListSkeleton.tsx`, and `QuestSkeleton.tsx`. These components are vital for providing a *graceful user experience* during data fetching or intensive operations. Instead of abrupt blank screens or spinners, skeletons offer a visual hint of the content to come, significantly improving perceived performance and user satisfaction. By grouping all skeleton components here, we ensure consistency in our loading states across the application and make it simple to implement new ones. This consolidation also helps to *move specific skeleton components from other domain-specific folders* (like `questsComponents/`) into a central, reusable location, eliminating duplication and promoting a unified approach to displaying loading states. This folder becomes the single source of truth for all loading placeholders, ensuring that our application always provides a smooth and professional loading experience.### The `layout/` Folder: App Shell & Core StructureThe `layout/` folder is all about the **app shell and core layout components**. This includes high-level components that define the overall structure of our application, such as `App.tsx`, `AppHeader.tsx`, `AppUpgradeScreen.tsx`, `MigrationScreen.tsx`, `AccountDeletedOverlay.tsx`, `LoadingView.tsx`, and `PrivateAccessGate.tsx`. These components are responsible for the foundational framework, global headers, full-screen states (like loading or upgrade screens), and access controls. By centralizing them, we ensure that the structural integrity and global experience of our application are consistently managed. Any changes to the main application container, header, or crucial full-screen overlays are found here. This separation helps to decouple the overall app structure from individual feature components, making it easier to reason about the high-level architecture and maintain a consistent layout across different views and states. This folder provides the canvas upon which all other features are painted, ensuring a unified and coherent user experience from the moment the app launches.### The `project/` Folder: Project-Related ComponentsThe `project/` folder is dedicated to **project-related components**. This includes components specifically designed for displaying information about projects, such as `ProjectDetails.tsx` and `ProjectCard.tsx`. For an application like `langquest`, where projects are a fundamental organizing principle for translation work, having a dedicated folder makes perfect sense. It ensures that all UI elements used to view, manage, or interact with projects are consolidated. This grouping makes it easier to find and update project-specific displays, ensuring consistency in how project information is presented throughout the application. It prevents project-related UI logic from being scattered, fostering a clearer understanding of the components that contribute to the project management interface. This folder becomes the definitive source for all UI elements that bring project data to life for the user.### The `quest/` Folder: Quest-Related ComponentsSimilar to projects, the `quest/` folder is for **quest-related components**. This is where we'll place `QuestCard.tsx`, `QuestDetails.tsx`, `QuestItem.tsx`, and `QuestsScreenStyles.tsx`. Quests are a core feature of `langquest`, representing discrete translation or language tasks. Consolidating all UI components related to displaying, interacting with, and styling quests into this folder provides immense clarity. This move also involves *absorbing components from the now-deprecated `questsComponents/` folder*, ensuring that all quest-specific UI elements have a single, logical home. By centralizing these, we make it much easier to develop new quest features, update existing quest displays, or apply consistent styling across all quest interfaces. This dedicated space helps in managing the complexity of quest interactions, from their visual representation to their detailed views, ultimately enhancing the user's ability to engage with their language learning journey.### The `asset/` Folder: Asset Display ComponentsThe `asset/` folder is for **asset display components**. This includes UI elements specifically designed for showing source content and translation cards, such as `SourceContent.tsx` and `TranslationCard.tsx`. In an application focused on content translation, `assets` (like source texts or audio segments) are crucial. This folder provides a clear home for components that render these assets and their associated translations. By grouping them, we ensure consistency in how content is presented to the user, making it easier to manage the display logic for different types of assets. It helps to keep the UI for content viewing distinct from other domain-specific components, fostering a modular and easy-to-understand structure. This folder becomes the go-to place for anything related to how our core content assets are visually represented and interacted with by the users.### The `language/` Folder: Language SelectionOur `language/` folder is for **language selection components**. This includes variations like `language-combobox.tsx`, `language-select.tsx`, and `LanguageSelect.tsx`. Given that `langquest` is all about languages, having a dedicated, well-organized space for these selection mechanisms is fundamental. This folder centralizes all the UI components that allow users to choose, filter, or manage languages within the application. By grouping these, we ensure consistency in language selection interfaces across various features, from project creation to personal settings. This makes it easier to implement new language pickers or update existing ones, ensuring a smooth and intuitive experience for users interacting with different languages. It also highlights the importance of language management within our application, providing a clear domain for these essential UI elements.### The `input/` Folder: Specialized Input ComponentsThe `input/` folder is for **specialized input components** that go beyond the basic primitives found in `ui/`. This includes elements like `ArrayInsertionList.tsx`, `ArrayInsertionWheel.tsx` (and its web variants), `CustomDropdown.tsx`, `PasswordInput.tsx`, `RadioSelect.tsx`, and `SwitchBox.tsx`. These are components that handle more complex user interactions or require specific input mechanisms not covered by simple `<input>` elements. By centralizing these specialized inputs, we ensure consistency in how users provide more intricate data to the application. This makes it easier to manage their state, validate input, and apply specific design patterns. It also prevents these more complex input controls from cluttering the general `ui/` folder, allowing `ui/` to remain focused on atomic primitives. This folder provides a clear home for advanced user interaction components, fostering a richer and more nuanced input experience.### The `carousel/` Folder: Carousel & Image DisplayThe `carousel/` folder is dedicated to **carousel and image display components**. This includes `Carousel.native.tsx`, `Carousel.tsx`, `Carousel.web.tsx`, and `ImageCarousel.tsx`. In applications that showcase media or multiple items in a rotating fashion, carousels are key UI elements. By grouping all carousel-related components here, especially those with platform-specific implementations, we ensure consistency in how carousels behave and appear across different environments. This makes it easier to manage the complex logic involved in sliding, animating, and displaying multiple items within a confined space. It also provides a clear separation for these interactive display mechanisms, allowing for easier maintenance and enhancement. This folder becomes the central hub for all components that facilitate dynamic content presentation through carousels, ensuring a visually engaging and interactive experience.### The `progress/` Folder: Progress Indicators & CountsThe `progress/` folder is for **progress indicators and counts**. This includes components like `DownloadIndicator.tsx`, `IndeterminateProgressBar.tsx`, `OnboardingProgressIndicator.tsx`, `PendingCount.tsx`, `PickaxeCount.tsx`, `ProgressBars.tsx`, and `SuccessCount.tsx`. These UI elements are crucial for providing users with *feedback* on ongoing operations, completion statuses, or achievements. By centralizing them, we ensure a consistent and clear way to communicate progress, whether it's a file download, an onboarding journey, or the count of completed tasks. This makes it easier to implement new progress indicators or update existing ones, contributing to a more transparent and user-friendly experience. This folder serves as the single source of truth for all components that visually represent the status and volume of various activities within the application, helping users stay informed and motivated.### The `export/` Folder: Export FunctionalityThe `export/` folder is for **export functionality-related UI**. This includes components such as `ExportButton.tsx` and `ExportTypeSelector.tsx`. In an application where users might need to export their data or work in various formats, having dedicated UI components for this process is essential. By grouping these elements, we ensure a consistent and intuitive experience for initiating and configuring data exports. This makes it easier to manage the logic behind selecting export options, triggering the export process, and displaying its status. It provides a clear separation for this specific functionality, preventing export-related UI from being scattered across different features. This folder becomes the go-to place for all components that facilitate the crucial task of data output, ensuring a streamlined and predictable user experience for content creators.### The `dev/` Folder: Development/Debug ToolsThe `dev/` folder is for **development and debug tools components**. This includes `OTAUpdateDebugControls.tsx` and `PerformanceDiagnostics.tsx`. These components are incredibly valuable during the development phase for testing, debugging, and monitoring application behavior, but they are typically *excluded from production builds*. By grouping them here, we clearly demarcate development-specific UI, making it easy to manage their visibility and ensure they don't accidentally ship to end-users. This separation helps in maintaining a clean production build while still providing powerful tools for developers to diagnose issues and optimize performance. It underscores our commitment to a robust development workflow, providing a dedicated space for all components that aid in the creation and refinement of our application without interfering with the end-user experience.### The `feedback/` Folder: Banners, Warnings, NotificationsThe `feedback/` folder is for **banners, warnings, and notifications**. This includes `OfflineUndownloadWarning.tsx`, `UpdateBanner.tsx`, and `FloatingMenu.tsx`. These components are crucial for communicating important information to the user, providing alerts, or offering contextual options. By centralizing them, we ensure a consistent approach to displaying user feedback, whether it's a critical warning about offline data, an announcement about an update, or a utility menu. This makes it easier to manage their visibility, styling, and interaction patterns, contributing to a more informative and responsive user interface. This folder serves as the primary location for all components that deliver timely messages and interactive elements outside of the main content flow, ensuring that users are always kept informed and engaged.### Cleanup Notes for Components1. **Delete `questsComponents/`**: This folder should be completely eliminated. Its contents should be *merged into `quest/`* for quest-specific components and *into `skeletons/`* for any quest-related loading states. This consolidation simplifies our component tree and removes redundancy.2. **Consolidate Language Selects**: We currently have `language-combobox.tsx`, `language-select.tsx`, AND `LanguageSelect.tsx`. This indicates potential duplication or unclear naming. We need to *consolidate these or at least clarify their distinct purposes and naming conventions* within the `language/` folder to avoid confusion. Perhaps one is a primitive, another a wrapper, etc. Let's make it crystal clear.3. **`theme-toggle.tsx`**: This component, being a primitive toggle control for themes, *could very well move into `ui/`*. It aligns perfectly with the purpose of `ui/` as a home for basic, reusable UI primitives.4. **Barrel Files (`index.ts`)**: Just like with hooks, guys, consider adding an `index.ts` barrel file in *each component subfolder*. This cleans up imports significantly, turning verbose paths into simple, readable statements, enhancing the developer experience.## Unlocking Utility: Streamlining Your `utils/` FolderLast but certainly not least, let's tackle our `utils` folder. This directory, often affectionately (or sometimes begrudgingly) known as the