How raymonds-dev/collectto works
1. Project shape
- This is a mobile app built with Expo + React Native + Expo Router.
- The runtime app is under src/; the rest of the repo is mostly developer workflow, specification management, and CI/branch automation.
2. Top-level navigation boundary
- src/app/ is the routing layer.
- It uses two main route groups:
- src/app/(auth) for unauthenticated flows
- src/app/(tabs) for the authenticated app shell
- src/app/_layout.tsx is the root boundary that wires providers and the auth gate before any screen renders.
3. Authentication and session flow
- AuthProvider bootstraps the user session on startup.
- Session state is persisted locally through src/services/storage/authSession.ts, backed by expo-secure-store per README.
- AuthGate decides whether the user goes to the login flow or into the main app area.
- The current login experience is mock/local, not backend-driven.
4. App domains
- The app is organized around a few core business areas:
- auth
- collections
- items
- posts
- comments
- profile
- settings
- These domains appear both in screen routes and in reusable components/providers/hooks.
5. State and domain context
- Domain state is lifted into React context providers:
- AuthProvider
- CollectionContextProvider
- ItemContextProvider
- PostContextProvider
- This suggests a pattern where screens stay mostly presentational and delegate data/state orchestration to context plus hooks.
6. Feature orchestration hooks
- src/hooks/ contains the main interaction logic for user flows:
- collection creation/editing
- item creation/editing/saving
- image picking
- photo permission handling
- authentication
- These hooks are the bridge between UI components and service/storage layers.
7. Service layer and data sources
- src/services/ is the main boundary for external effects.
- It includes:
- api/ for backend integration shape
- photo-storage/ with a factory and a local provider
- storage/ for local persistence utilities
- debug/ for mock implementations and debug session behavior
- The app currently leans heavily on mock/debug services, which makes local execution and testing possible without a live backend.
8. Debug mode as a first-class path
- src/services/debug/ contains mock auth, collection, item, and post services plus session lifecycle/debug flags.
- src/mocks/ provides seed data and fixtures.
- This is a distinct architecture path: production-style contracts exist, but the app can run against local deterministic data for development and feature work.
9. UI composition
- src/components/ holds reusable UI and domain widgets.
- There’s a clear split between:
- generic UI primitives in src/components/ui
- domain components like collections, items, comments, profile, settings, and create-item flows
- Screens in src/app/ are mostly assembled from these components rather than containing deep logic.
10. Media and permission flow
- The create-item flow has its own subsystem:
- permission request/gating
- photo picking
- preview and save steps
- success confirmation
- Photo handling is abstracted through src/services/photo-storage/ and related hooks, which is a notable boundary for mobile-specific behavior.
11. Design system and presentation layer
- Styling is centralized via NativeWind + Tailwind.
- Tokens live in src/styles/tailwind/, with global styles in src/styles/global.css.
- src/components/ui/ provides shared visual controls, including animated wrappers and custom pickers.
- This keeps style concerns separate from domain logic.
12. Types and utility boundary
- src/types/ defines the shared data contracts for auth, collections, items, comments, settings, and photo storage.
- src/utils/ contains small pure helpers like date formatting, ID generation, and comment/post ID extraction.
- These act as the stable data-shape layer across UI, hooks, and services.
13. Feature specifications and contracts
- The specs/ directory is a major repo subsystem, but not part of the runtime app.
- It contains feature-by-feature specs, plans, tasks, data models, and contract files for items like feed comments, item collection, debug mode, and collection/item management.
- For architecture diagrams, this is best shown as an engineering workflow/requirements layer feeding implementation, not as app runtime code.
14. Repo governance and automation
- .github/, .specify/, .agents/, and .gemini/ define AI-assisted workflows, prompts, commands, and GitHub automation.
- CI validates the repo, and branch/PR automation helps manage feature flow.
- These are supporting systems around the codebase, useful to show as the repo’s delivery pipeline rather than application architecture.
15. Overall data flow
- Typical flow is:
- route screen mounts
- provider exposes domain state
- hook drives interaction and side effects
- service reads/writes local storage or mock/debug data
- UI updates from context/state
- The main architectural boundary is between presentation/navigation and services/state orchestration, with local persistence and mock services standing in for backend integration today.
Main entry points: hooks Feature hooks · debug Debug services · _layout.tsx App shell · components Domain components
Components 20
Runtime app
Expo Router app, providers, hooks, UI, and domain features under src/
- App shell · Root layout that wires providers and the auth gate before screens render
src/app/_layout.tsx - Auth routes · Unauthenticated flows and login entry screens
src/app/(auth) - Tab shell · Authenticated app shell and primary tabs
src/app/(tabs) - Collection routes · Collection detail and edit screens outside the main tab shell
src/app/collections - Context providers · Shared domain state for auth, collections, items, and posts
src/providers - Auth provider · Bootstraps and exposes user session state
src/providers/AuthProvider.tsx - Domain providers · Collection, item, and post state orchestration for screens
src/providers/CollectionContextProvider.tsx - Feature hooks · Orchestrates create/edit/save flows, auth, image picking, and permissions
src/hooks - Domain components · Reusable widgets for collections, items, comments, posts, profile, settings, and create-item flows
src/components - UI system · Shared primitives, animated wrappers, pickers, and visual controls
src/components/ui - Style tokens · NativeWind and Tailwind tokens plus global styles
src/styles - Shared types · Core data shapes for auth, collections, items, comments, settings, and photo storage
src/types - Pure utils · Small stateless helpers for dates, IDs, and post/comment identifiers
src/utils
Platform services
Local persistence, mock/debug services, and API-facing boundaries
- Local storage · Session persistence for authenticated state
src/services/storage/authSession.ts - Debug services · Mock auth, collection, item, and post services with session lifecycle controls
src/services/debug - Photo storage · Factory and local provider for image/photo handling
src/services/photo-storage - API boundary · Backend-facing API shape and integration reference
src/services/api - Seed mocks · Deterministic debug data and sample content
src/mocks
Engineering workflow
Specs, agent prompts, and CI/branch automation outside the runtime app
- Feature specs · Specs, plans, tasks, data models, and contracts that drive implementation
specs - Repo automation · GitHub workflows, agent prompts, and Specify/Gemini/Speckit automation
.github
Connections 24
- App shell → Context providers: wraps · Root layout composes app-wide providers
- App shell → Auth routes: routes · Auth gate can send users into unauthenticated flows
- App shell → Tab shell: routes · Authenticated users enter the tab shell
- App shell → Collection routes: routes · Root navigation includes collection detail/edit screens
- Context providers → Auth provider: includes · Auth context is a top-level provider
- Context providers → Domain providers: includes · Collection, item, and post contexts are grouped together
- Auth provider → Local storage: persists · Session state is saved locally
- Auth provider → Debug services: boots · Debug auth/session logic supports local startup
- Tab shell → Domain components: assembles · Primary app screens are composed from reusable domain UI
- Auth routes → Feature hooks: uses · Login and account flows rely on interaction hooks
- Tab shell → Feature hooks: uses · Tab screens delegate interactions and side effects to hooks
- Collection routes → Domain components: renders · Collection detail/edit routes are built from feature components
- Feature hooks → Debug services: calls · Main flows use mock/debug services when backend is absent
- Feature hooks → Photo storage: uses · Item creation and media flows depend on photo storage abstractions
- Feature hooks → Pure utils: derives · Hooks use pure helpers for IDs and formatting
- Domain components → UI system: builds on · Domain widgets compose shared UI primitives
- UI system → Style tokens: styled by · Visual primitives are themed through Tailwind tokens and global styles
- Domain components → Shared types: shapes · Components consume shared data contracts
- Feature hooks → Shared types: depends on · Interaction logic is typed by shared domain contracts
- Debug services → Seed mocks: seeds · Mock services use deterministic fixture data
- Feature specs → API boundary: defines · Specs capture contracts for runtime implementation
- Feature specs → Debug services: informs · Debug-mode specs align with mock service behavior
- Repo automation → Feature specs: manages · Automation supports spec, plan, and task workflows
- Repo automation → Debug services: validates · CI and branch automation help preserve repo behavior