# raymonds-dev/collectto architecture

> Architecture diagram of the GitHub repository raymonds-dev/collectto, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raymonds-dev/collectto
- Repository: https://github.com/raymonds-dev/collectto

## Overview

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: [`src/hooks`](https://github.com/raymonds-dev/collectto/tree/main/src/hooks) (Feature hooks), [`src/services/debug`](https://github.com/raymonds-dev/collectto/tree/main/src/services/debug) (Debug services), [`src/app/_layout.tsx`](https://github.com/raymonds-dev/collectto/blob/main/src/app/_layout.tsx) (App shell), [`src/components`](https://github.com/raymonds-dev/collectto/tree/main/src/components) (Domain components)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime app"]
  node_app_layout["App shell<br/>expo-router root<br/>[_layout.tsx]"]
  node_auth_routes["Auth routes<br/>route group"]
  node_tab_routes["Tab shell<br/>route group"]
  node_collection_routes["Collection routes<br/>detail routes"]
  node_providers["Context providers<br/>react context"]
  node_auth_provider["Auth provider<br/>session context<br/>[AuthProvider.tsx]"]
  node_domain_providers["Domain providers<br/>state context"]
  node_hooks["Feature hooks<br/>interaction logic"]
  node_domain_components["Domain components<br/>feature UI"]
  node_ui_system["UI system<br/>design system"]
  node_styles["Style tokens<br/>tailwind theme"]
  node_types["Shared types<br/>contracts"]
  node_utils["Pure utils<br/>helpers"]
end

subgraph group_platform["Platform services"]
  node_storage[("Local storage<br/>persistence<br/>[authSession.ts]")]
  node_debug_services["Debug services<br/>mock runtime"]
  node_photo_storage["Photo storage<br/>media boundary"]
  node_api_boundary["API boundary<br/>backend contract"]
  node_mocks["Seed mocks<br/>fixtures"]
end

subgraph group_workflow["Engineering workflow"]
  node_specs["Feature specs<br/>requirements layer"]
  node_automation["Repo automation<br/>ai/ci workflow<br/>[.github]"]
end

node_app_layout -->|"wraps"| node_providers
node_app_layout -->|"routes"| node_auth_routes
node_app_layout -->|"routes"| node_tab_routes
node_app_layout -->|"routes"| node_collection_routes
node_providers -->|"includes"| node_auth_provider
node_providers -->|"includes"| node_domain_providers
node_auth_provider -->|"persists"| node_storage
node_auth_provider -->|"boots"| node_debug_services
node_tab_routes -->|"assembles"| node_domain_components
node_auth_routes -->|"uses"| node_hooks
node_tab_routes -->|"uses"| node_hooks
node_collection_routes -->|"renders"| node_domain_components
node_hooks -->|"calls"| node_debug_services
node_hooks -->|"uses"| node_photo_storage
node_hooks -->|"derives"| node_utils
node_domain_components -->|"builds on"| node_ui_system
node_ui_system -->|"styled by"| node_styles
node_domain_components -->|"shapes"| node_types
node_hooks -->|"depends on"| node_types
node_debug_services -->|"seeds"| node_mocks
node_specs -.->|"defines"| node_api_boundary
node_specs -.->|"informs"| node_debug_services
node_automation -.->|"manages"| node_specs
node_automation -.->|"validates"| node_debug_services

click node_app_layout "https://github.com/raymonds-dev/collectto/blob/main/src/app/_layout.tsx"
click node_auth_routes "https://github.com/raymonds-dev/collectto/tree/main/src/app/(auth)"
click node_tab_routes "https://github.com/raymonds-dev/collectto/tree/main/src/app/(tabs)"
click node_collection_routes "https://github.com/raymonds-dev/collectto/tree/main/src/app/collections"
click node_providers "https://github.com/raymonds-dev/collectto/tree/main/src/providers"
click node_auth_provider "https://github.com/raymonds-dev/collectto/blob/main/src/providers/AuthProvider.tsx"
click node_domain_providers "https://github.com/raymonds-dev/collectto/blob/main/src/providers/CollectionContextProvider.tsx"
click node_hooks "https://github.com/raymonds-dev/collectto/tree/main/src/hooks"
click node_domain_components "https://github.com/raymonds-dev/collectto/tree/main/src/components"
click node_ui_system "https://github.com/raymonds-dev/collectto/tree/main/src/components/ui"
click node_styles "https://github.com/raymonds-dev/collectto/tree/main/src/styles"
click node_types "https://github.com/raymonds-dev/collectto/tree/main/src/types"
click node_utils "https://github.com/raymonds-dev/collectto/tree/main/src/utils"
click node_storage "https://github.com/raymonds-dev/collectto/blob/main/src/services/storage/authSession.ts"
click node_debug_services "https://github.com/raymonds-dev/collectto/tree/main/src/services/debug"
click node_photo_storage "https://github.com/raymonds-dev/collectto/tree/main/src/services/photo-storage"
click node_api_boundary "https://github.com/raymonds-dev/collectto/tree/main/src/services/api"
click node_mocks "https://github.com/raymonds-dev/collectto/tree/main/src/mocks"
click node_specs "https://github.com/raymonds-dev/collectto/tree/main/specs"
click node_automation "https://github.com/raymonds-dev/collectto/blob/main/.github"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_layout,node_auth_routes,node_tab_routes,node_collection_routes,node_providers,node_auth_provider,node_domain_providers,node_hooks,node_domain_components,node_ui_system,node_styles,node_types,node_utils toneBlue
class node_storage,node_debug_services,node_photo_storage,node_api_boundary,node_mocks toneAmber
class node_specs,node_automation toneMint
```

## Components

### Runtime app

Expo Router app, providers, hooks, UI, and domain features under src/

- [App shell](https://github.com/raymonds-dev/collectto/blob/main/src/app/_layout.tsx): expo-router root · Root layout that wires providers and the auth gate before screens render · `src/app/_layout.tsx`
- [Auth routes](https://github.com/raymonds-dev/collectto/tree/main/src/app/(auth)): route group · Unauthenticated flows and login entry screens · `src/app/(auth)`
- [Tab shell](https://github.com/raymonds-dev/collectto/tree/main/src/app/(tabs)): route group · Authenticated app shell and primary tabs · `src/app/(tabs)`
- [Collection routes](https://github.com/raymonds-dev/collectto/tree/main/src/app/collections): detail routes · Collection detail and edit screens outside the main tab shell · `src/app/collections`
- [Context providers](https://github.com/raymonds-dev/collectto/tree/main/src/providers): react context · Shared domain state for auth, collections, items, and posts · `src/providers`
- [Auth provider](https://github.com/raymonds-dev/collectto/blob/main/src/providers/AuthProvider.tsx): session context · Bootstraps and exposes user session state · `src/providers/AuthProvider.tsx`
- [Domain providers](https://github.com/raymonds-dev/collectto/blob/main/src/providers/CollectionContextProvider.tsx): state context · Collection, item, and post state orchestration for screens · `src/providers/CollectionContextProvider.tsx`
- [Feature hooks](https://github.com/raymonds-dev/collectto/tree/main/src/hooks): interaction logic · Orchestrates create/edit/save flows, auth, image picking, and permissions · `src/hooks`
- [Domain components](https://github.com/raymonds-dev/collectto/tree/main/src/components): feature UI · Reusable widgets for collections, items, comments, posts, profile, settings, and create-item flows · `src/components`
- [UI system](https://github.com/raymonds-dev/collectto/tree/main/src/components/ui): design system · Shared primitives, animated wrappers, pickers, and visual controls · `src/components/ui`
- [Style tokens](https://github.com/raymonds-dev/collectto/tree/main/src/styles): tailwind theme · NativeWind and Tailwind tokens plus global styles · `src/styles`
- [Shared types](https://github.com/raymonds-dev/collectto/tree/main/src/types): contracts · Core data shapes for auth, collections, items, comments, settings, and photo storage · `src/types`
- [Pure utils](https://github.com/raymonds-dev/collectto/tree/main/src/utils): helpers · 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](https://github.com/raymonds-dev/collectto/blob/main/src/services/storage/authSession.ts): persistence · Session persistence for authenticated state · `src/services/storage/authSession.ts`
- [Debug services](https://github.com/raymonds-dev/collectto/tree/main/src/services/debug): mock runtime · Mock auth, collection, item, and post services with session lifecycle controls · `src/services/debug`
- [Photo storage](https://github.com/raymonds-dev/collectto/tree/main/src/services/photo-storage): media boundary · Factory and local provider for image/photo handling · `src/services/photo-storage`
- [API boundary](https://github.com/raymonds-dev/collectto/tree/main/src/services/api): backend contract · Backend-facing API shape and integration reference · `src/services/api`
- [Seed mocks](https://github.com/raymonds-dev/collectto/tree/main/src/mocks): fixtures · Deterministic debug data and sample content · `src/mocks`

### Engineering workflow

Specs, agent prompts, and CI/branch automation outside the runtime app

- [Feature specs](https://github.com/raymonds-dev/collectto/tree/main/specs): requirements layer · Specs, plans, tasks, data models, and contracts that drive implementation · `specs`
- [Repo automation](https://github.com/raymonds-dev/collectto/blob/main/.github): ai/ci workflow · GitHub workflows, agent prompts, and Specify/Gemini/Speckit automation · `.github`

## Connections

- 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