# sheldonblewis/reach-new-builds-2024 architecture

> Architecture diagram of the GitHub repository sheldonblewis/reach-new-builds-2024, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sheldonblewis/reach-new-builds-2024
- Repository: https://github.com/sheldonblewis/reach-new-builds-2024

## Overview

##### Establish the Project Context and Overall Layers
- Project Type: A full-stack, multi-platform application for urban exploration and art discovery.
- Key Purposes: Immersive AR experience, local artist exploration, community-building, and interactive urban art voting.
- Main Layers: Mobile Client, Web Prototype, Backend Services, Database, and External Services.

##### Main Components
a. Mobile Component (Expo App)
- Directory: expo/
- Role: Provides the augmented reality experience on mobile devices. It includes components (UI elements, hooks, configuration for connectivity to external services), styles, and routing (with segmented layouts, modals, pages).
- Key Technologies: Expo, React Native, TypeScript, Tailwind CSS, and integration configs for Firebase and Supabase.

b. Web Prototype
- Directory: web-spotify-proto/
- Role: Acts as a proof-of-concept or additional web interface. Likely focused on music/artist discovery integration.
- Key Technologies: Standard web stack (HTML, TypeScript).

c. Python Backend Service
- Directory: backend/
- Role: Contains core functionalities (e.g., interpreter, search routines, sample code) that may handle data processing, computational aspects, or specialized search/interrogation methods.
- Key Technologies: Python scripts, likely with dependencies as listed in requirements.txt.

d. Node.js Server API Service
- Directory: node-server/
- Role: Acts as a robust API server handling data fetching, database interactions, and integrations with external APIs (such as Spotify and Wikipedia for artist data). It houses routing logic, database schema and migrations, error handling, and modules related to artist and genre management.
- Key Technologies: Node.js, TypeScript, and database migration tools (drizzle.config, SQL scripts).

e. Database and Persistence Layer
- Location: Managed within node-server/src/db/ (includes migrations, schema, helper functions).
- Role: Stores persistent data relating to artists, genres, and possibly user data. This database is accessed by the Node.js server.

f. External Services and APIs
- Mentioned in expo/config (Firebase, Node, Supabase) and references within node-server (Spotify, Wikipedia).
- Role: Provide authentication, real-time data, and external content integration.

##### Relationships and Interactions
- The Mobile App (Expo) and Web Prototype act as client-facing interfaces. They interact with backend services.
- The Node.js server provides RESTful (or possibly GraphQL) endpoints and communicates with the database for CRUD operations and artist data retrieval.
- The Python backend might be an independent service or deployed as a microservice to process complex queries or perform specialized tasks.
- External services (Firebase, Supabase, Spotify, Wikipedia) are integrated as complementary data sources and authentication providers.
- Data flow typically starts at a client (mobile or web), which sends requests to the Node.js API; the API accesses the database and may call the Python backend for more specialized processing, then replies back to the client.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clear division between the user interfaces (mobile/web), business logic (Node.js server and Python backend), and data persistence (database).
- Modular Structure: Each directory is purpose-built and decoupled as much as possible (e.g., expo for client, node-server for API, backend for processing).
- Use of Microservices (Optional): The Python backend service might operate as a microservice that the Node.js server calls if complex data processing is needed.
- API-Driven Communication: Use of REST or similar patterns for clear communication channels between clients and backend services.

##### Elements
- Additional Notations: Optionally highlight the use of microservices architecture or middleware layers if present.

- With technology keywords (e.g., “React Native”, “TypeScript”, “Python”, “SQL migrations”, “Firebase”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Clients"
        subgraph "Mobile App (Expo)"
            MA_UI["UI Components (expo/app)"]:::mobile
            MA_Config["Configuration (expo/config)"]:::mobile
        end
        WP["Web Prototype (index & src)"]:::web
    end

    subgraph "Backend Services"
        API["API Server (Node.js/TypeScript)"]:::backend
        PY["Python Processing Service (Python)"]:::python
    end

    subgraph "Data & External"
        DB["Database (node-server/src/db)"]:::database
        subgraph "External Services"
            FB["Firebase"]:::external
            SB["Supabase"]:::external
            SP["Spotify"]:::external
            WP2["Wikipedia"]:::external
        end
    end

    %% Connections
    MA_UI -->|"sendsReq"| API
    WP -->|"sendsReq"| API
    API -->|"queries"| DB
    API <-->|"calls"| PY
    API -->|"integrates"| SP
    API -->|"integrates"| WP2
    MA_Config -->|"connects"| FB
    MA_Config -->|"connects"| SB

    %% Click Events
    click MA_UI "https://github.com/sheldonblewis/reach-new-builds-2024/tree/master/expo/app/"
    click MA_Config "https://github.com/sheldonblewis/reach-new-builds-2024/tree/master/expo/config/"
    click WP "https://github.com/sheldonblewis/reach-new-builds-2024/blob/master/web-spotify-proto/index.html"
    click PY "https://github.com/sheldonblewis/reach-new-builds-2024/blob/master/backend/main.py"
    click API "https://github.com/sheldonblewis/reach-new-builds-2024/tree/master/node-server/src/"
    click DB "https://github.com/sheldonblewis/reach-new-builds-2024/tree/master/node-server/src/db/"
    click FB "https://github.com/sheldonblewis/reach-new-builds-2024/blob/master/expo/config/firebase.ts"
    click SB "https://github.com/sheldonblewis/reach-new-builds-2024/blob/master/expo/config/supabase.ts"
    click SP "https://github.com/sheldonblewis/reach-new-builds-2024/tree/master/node-server/src/spotify/"
    click WP2 "https://github.com/sheldonblewis/reach-new-builds-2024/blob/master/node-server/src/artists/fetchers/wikipedia.ts"

    %% Styles
    classDef mobile fill:#fceabb,stroke:#e0a800,stroke-width:2px;
    classDef web fill:#d5f4e6,stroke:#3b7a57,stroke-width:2px;
    classDef backend fill:#f7cac9,stroke:#c94c4c,stroke-width:2px;
    classDef python fill:#f1c40f,stroke:#d68910,stroke-width:2px;
    classDef database fill:#dfe6e9,stroke:#b2bec3,stroke-width:2px;
    classDef external fill:#cad3c8,stroke:#95a5a6,stroke-width:2px;
```
