# yougotnothing/inspace architecture

> Architecture diagram of the GitHub repository yougotnothing/inspace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yougotnothing/inspace
- Repository: https://github.com/yougotnothing/inspace

## Overview

##### Project type and purpose
- This is a full-stack, microservices-style web application (“InSpace”) that aggregates and displays space events (moon phases, eclipses, meteor showers, etc.), air and light pollution data, and lets users “spot” events and receive email notifications.
- The stack comprises:
- A GraphQL backend (NestJS + Prisma + PostgreSQL + Redis + MinIO + SMTP/email)
- A React/Apollo/Vite frontend
- A Python FastAPI microservice (OAuth flows & geolocation routes)
- Docker/Docker-Compose for orchestration

##### File structure
Top-level folders:
- api – NestJS GraphQL server with modules for auth, events, pollution, geolocation, email, user profiles, file uploads (MinIO), Redis caching, Prisma migrations/schema, Pug email templates, GraphQL schema/resolvers.
- frontend – React SPA using Apollo Client, Vite, styled-components, custom hooks, TypeScript types, validation schemas.
- python – FastAPI service handling external OAuth (Google, GitHub, OpenID Connect/Keycloak) and geolocation routes.
- docker-compose.yml – ties together API, frontend, Python service, Postgres, Redis, MinIO, Keycloak (via wait script).

##### README for additional insights
- Clearly states project idea and feature set (GraphQL integration, three.js UI, email, OAuth, “toSpotted”).
- Tech badges show NestJS, Prisma, React, GraphQL, Apollo, FastAPI, Docker, etc.
- In-process checklist reveals which features are live.

##### Additional details to enhance informativeness
- Sequence: User logs in → Apollo sends login mutation → Auth module issues JWT → Redis stores session → Frontend stores tokens.
- How Prisma migrations evolve the DB schema over time.
- Three.js starfield & moon render as part of the Frontend’s UI component.
- “toSpotted” flow: user marks event → GraphQL mutation → Event module persists spotted flag → Notification module sends email if new.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend
    subgraph "Frontend Client"
        FC["React/Apollo Client"]:::frontend
    end

    %% API Service
    subgraph "GraphQL API Service"
        API["NestJS GraphQL API"]:::backend
        subgraph "Auth Module"
            Auth["Auth Module"]:::backend
        end
        subgraph "Events Module"
            Events["Events Module"]:::backend
        end
        subgraph "Pollution Module"
            Pollution["Air & Light Pollution Module"]:::backend
        end
        subgraph "Geolocation Module"
            GeoMod["Geolocation Module"]:::backend
        end
        subgraph "Email Module"
            Email["Email Module"]:::backend
        end
        subgraph "User Profiles & Avatars"
            User["User Profile Module"]:::backend
        end
        subgraph "File Uploads"
            MinIOmod["MinIO Module"]:::backend
        end
        subgraph "Redis Caching"
            RedisMod["Redis Module"]:::backend
        end
        subgraph "Prisma ORM"
            PrismaMod["Prisma & Migrations"]:::backend
        end
    end

    %% Python Service
    subgraph "Python OAuth & Geo Service"
        PY["FastAPI Service"]:::backend
    end

    %% Data Stores
    subgraph "Data Stores"
        PG[(PostgreSQL)]:::db
        RD[(Redis)]:::db
        MI[(MinIO)]:::db
    end

    %% External Services
    subgraph "External Services"
        GO[(Google OAuth)]:::external
        GH[(GitHub OAuth)]:::external
        KC[(Keycloak)]:::external
        SMTP[(SMTP Email)]:::external
        GEOAPI[(Third-party Geo API)]:::external
    end

    %% Connections
    FC -->|"GraphQL requests"| API
    FC -->|"OAuth redirects"| PY
    API -->|"Prisma ORM calls"| PG
    API -->|"Cache & sessions"| RD
    API -->|"Upload/download"| MI
    API -->|"Send emails"| SMTP
    API -->|"OAuth handshake / Geo lookup"| PY
    PY -->|"OAuth token exchange"| GO
    PY -->|"OAuth token exchange"| GH
    PY -->|"OIDC flows"| KC
    PY -->|"Geo queries"| GEOAPI

    %% Click Events
    click FC "https://github.com/yougotnothing/inspace/tree/main/frontend/"
    click API "https://github.com/yougotnothing/inspace/tree/main/api/"
    click Auth "https://github.com/yougotnothing/inspace/blob/main/api/src/main/module/auth.module.ts"
    click Events "https://github.com/yougotnothing/inspace/blob/main/api/src/main/module/event.module.ts"
    click Pollution "https://github.com/yougotnothing/inspace/blob/main/api/src/main/module/air-pollution.module.ts"
    click GeoMod "https://github.com/yougotnothing/inspace/blob/main/api/src/main/module/geolocation.module.ts"
    click Email "https://github.com/yougotnothing/inspace/blob/main/api/src/main/module/email.module.ts"
    click User "https://github.com/yougotnothing/inspace/blob/main/api/src/main/module/user.module.ts"
    click MinIOmod "https://github.com/yougotnothing/inspace/blob/main/api/src/main/module/minio.module.ts"
    click RedisMod "https://github.com/yougotnothing/inspace/blob/main/api/src/main/module/redis.module.ts"
    click PrismaMod "https://github.com/yougotnothing/inspace/blob/main/api/prisma/schema.prisma"
    click PY "https://github.com/yougotnothing/inspace/blob/main/python/main.py"
    click PG "https://github.com/yougotnothing/inspace/blob/main/docker-compose.yml"
    click MI "https://github.com/yougotnothing/inspace/blob/main/docker-compose.yml"
    click RD "https://github.com/yougotnothing/inspace/blob/main/docker-compose.yml"
    click GO "https://github.com/yougotnothing/inspace/blob/main/python/routes/google_oauth.py"
    click GH "https://github.com/yougotnothing/inspace/blob/main/python/routes/github_oauth.py"
    click KC "https://github.com/yougotnothing/inspace/blob/main/python/routes/openid_connect.py"
    click GEOAPI "https://github.com/yougotnothing/inspace/blob/main/python/routes/geolocation.py"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366d6,color:#0366d6,stroke-width:1px;
    classDef backend fill:#DFFFE0,stroke:#238636,color:#22863a,stroke-width:1px;
    classDef db fill:#FFE0B2,stroke:#e65100,color:#e65100,stroke-width:1px;
    classDef external fill:#E0E0E0,stroke:#6a737d,color:#57606a,stroke-width:1px;
```
