# azeem07112007/cosmera architecture

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

- Interactive diagram: https://gitdiagram.com/azeem07112007/cosmera
- Repository: https://github.com/azeem07112007/cosmera

## Overview

#### Purpose and Entry Point
Cosmera is a browser-based astronomy platform that classifies uploaded images into galaxies, nebulae, stars, or asteroids, then provides AI-generated astronomy explanations and comparisons. The runtime entry point is the FastAPI application in `app.py`; it is launched with Python or Uvicorn.

#### API and Orchestration Layer
`app.py` is the system boundary between the browser UI, image-classification pipeline, and Lumina assistant integration. It serves the platform and coordinates requests that require inference or AI responses. `ollama_test.py` and `diag.py` appear to support model/API diagnostics rather than core application flow.

#### Vision Classification Pipeline
The custom PyTorch CNN lifecycle is split between training and inference:
- `train.py` prepares/trains the CNN from labeled astronomy images.
- `predict.py` loads the trained inference pipeline for image classification.
- `classes.json` provides the class-label mapping returned to application/UI consumers.

The primary inference flow is: browser image upload → FastAPI orchestration → PyTorch prediction → mapped cosmic-object label → explanatory AI context.

#### Dataset and Model Boundary
Training data is organized by object category under:
- `dataset/galaxy`
- `dataset/nebula`
- `dataset/stars`
- `dataset/asteroids`

This directory-per-class structure is the key contract between the dataset, `train.py`, and `classes.json`. The repository describes CPU-optimized PyTorch dependencies in `requirements.txt`, making local or constrained cloud inference/training a material deployment consideration.

#### Lumina AI Integration
Lumina is an external Llama 3-based astronomy assistant accessed through the NVIDIA NIM API. The application requires an `NVIDIA_API_KEY` supplied through a root `.env` file; API credentials are intentionally outside tracked source. Lumina consumes classification results and conversational context to generate object explanations, formation summaries, follow-up answers, and image-comparison analysis.

#### Browser Experience and Interaction Surfaces
The frontend is static HTML/CSS/JavaScript served by the application:
- `index.html` is the primary landing surface.
- `identify.html` supports object-identification interaction.
- `compare.html` supports two-image comparison.
- `learn.html` supports educational content.
- `cosmic-animations.js` and `cosmic-animations.css` implement the interactive/visual presentation layer.

The client is responsible for image selection, chat/comparison interaction, and displaying classification plus Lumina responses; server-side services own model inference and external AI calls.

#### Main Control Flows
1. **Identification:** `identify.html` submits an astronomy image to `app.py`; `predict.py` classifies it using the trained CNN and `classes.json`; the result can be sent to NVIDIA NIM for a scientific explanation.
2. **Assistant follow-up:** browser conversation state and latest scan context are submitted through `app.py` to Lumina, which returns context-aware responses.
3. **Comparison:** `compare.html` supplies two astronomical inputs; `app.py` delegates the AI-driven comparative interpretation to the Lumina/NVIDIA NIM boundary.

Main entry points: [`app.py`](https://github.com/azeem07112007/cosmera/blob/main/app.py) (FastAPI orchestration), [`train.py`](https://github.com/azeem07112007/cosmera/blob/main/train.py) (CNN training), [`predict.py`](https://github.com/azeem07112007/cosmera/blob/main/predict.py) (CNN inference), [`identify.html`](https://github.com/azeem07112007/cosmera/blob/main/identify.html) (Identify experience)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser UI"]
  node_index["Landing page<br/>HTML<br/>[index.html]"]
  node_identify["Identify experience<br/>HTML<br/>[identify.html]"]
  node_compare["Comparison experience<br/>HTML<br/>[compare.html]"]
  node_learn["Learning content<br/>HTML<br/>[learn.html]"]
  node_animations_js["Interactive visuals<br/>JavaScript"]
  node_animations_css["Cosmic styling<br/>CSS"]
end

subgraph group_server["Application"]
  node_app{{"FastAPI orchestration<br/>FastAPI app<br/>[app.py]"}}
end

subgraph group_ml["Vision ML"]
  node_predict["CNN inference<br/>PyTorch<br/>[predict.py]"]
  node_classes["Class labels<br/>Label mapping<br/>[classes.json]"]
  node_train["CNN training<br/>PyTorch<br/>[train.py]"]
end

subgraph group_data["Training Data"]
  node_galaxy_data[("Galaxy images<br/>Dataset class")]
  node_nebula_data[("Nebula images<br/>Dataset class")]
  node_stars_data[("Star images<br/>Dataset class")]
  node_asteroids_data[("Asteroid images<br/>Dataset class")]
end

subgraph group_external["External AI"]
  node_lumina{{"Lumina assistant"}}
  node_api_key["NVIDIA API key<br/>Credential"]
end

node_index -->|"served by"| node_app
node_identify -->|"image upload and chat"| node_app
node_compare -->|"two-image comparison"| node_app
node_learn -->|"served by"| node_app
node_animations_js -->|"interactive UI"| node_identify
node_animations_css -->|"visual presentation"| node_identify
node_app -->|"classification request"| node_predict
node_predict -->|"maps output"| node_classes
node_app -->|"explanations, chat, comparison"| node_lumina
node_predict -->|"classification context"| node_lumina
node_api_key -.->|"authenticates API access"| node_lumina
node_galaxy_data -->|"labeled training images"| node_train
node_nebula_data -->|"labeled training images"| node_train
node_stars_data -->|"labeled training images"| node_train
node_asteroids_data -->|"labeled training images"| node_train
node_train -->|"trained CNN"| node_predict
node_train -.->|"class contract"| node_classes

click node_index "https://github.com/azeem07112007/cosmera/blob/main/index.html"
click node_identify "https://github.com/azeem07112007/cosmera/blob/main/identify.html"
click node_compare "https://github.com/azeem07112007/cosmera/blob/main/compare.html"
click node_learn "https://github.com/azeem07112007/cosmera/blob/main/learn.html"
click node_animations_js "https://github.com/azeem07112007/cosmera/blob/main/cosmic-animations.js"
click node_animations_css "https://github.com/azeem07112007/cosmera/blob/main/cosmic-animations.css"
click node_app "https://github.com/azeem07112007/cosmera/blob/main/app.py"
click node_predict "https://github.com/azeem07112007/cosmera/blob/main/predict.py"
click node_classes "https://github.com/azeem07112007/cosmera/blob/main/classes.json"
click node_train "https://github.com/azeem07112007/cosmera/blob/main/train.py"
click node_galaxy_data "https://github.com/azeem07112007/cosmera/tree/main/dataset/galaxy"
click node_nebula_data "https://github.com/azeem07112007/cosmera/tree/main/dataset/nebula"
click node_stars_data "https://github.com/azeem07112007/cosmera/tree/main/dataset/stars"
click node_asteroids_data "https://github.com/azeem07112007/cosmera/tree/main/dataset/asteroids"

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_index,node_identify,node_compare,node_learn,node_animations_js,node_animations_css toneBlue
class node_app toneAmber
class node_predict,node_classes,node_train toneMint
class node_galaxy_data,node_nebula_data,node_stars_data,node_asteroids_data toneRose
class node_lumina,node_api_key toneIndigo
```

## Components

### Browser UI

- [Landing page](https://github.com/azeem07112007/cosmera/blob/main/index.html): HTML · `index.html`
- [Identify experience](https://github.com/azeem07112007/cosmera/blob/main/identify.html): HTML · Uploads an image and displays classification and explanations. · `identify.html`
- [Comparison experience](https://github.com/azeem07112007/cosmera/blob/main/compare.html): HTML · Collects two astronomical inputs for AI comparison. · `compare.html`
- [Learning content](https://github.com/azeem07112007/cosmera/blob/main/learn.html): HTML · `learn.html`
- [Interactive visuals](https://github.com/azeem07112007/cosmera/blob/main/cosmic-animations.js): JavaScript · `cosmic-animations.js`
- [Cosmic styling](https://github.com/azeem07112007/cosmera/blob/main/cosmic-animations.css): CSS · `cosmic-animations.css`

### Application

- [FastAPI orchestration](https://github.com/azeem07112007/cosmera/blob/main/app.py): FastAPI app · Serves the browser surfaces and coordinates inference and Lumina requests. · `app.py`

### Vision ML

- [CNN inference](https://github.com/azeem07112007/cosmera/blob/main/predict.py): PyTorch · Loads the trained prediction pipeline for uploaded images. · `predict.py`
- [Class labels](https://github.com/azeem07112007/cosmera/blob/main/classes.json): Label mapping · Maps model outputs to cosmic-object labels. · `classes.json`
- [CNN training](https://github.com/azeem07112007/cosmera/blob/main/train.py): PyTorch · Trains the custom classifier from labeled astronomy images. · `train.py`

### Training Data

- [Galaxy images](https://github.com/azeem07112007/cosmera/tree/main/dataset/galaxy): Dataset class · `dataset/galaxy`
- [Nebula images](https://github.com/azeem07112007/cosmera/tree/main/dataset/nebula): Dataset class · `dataset/nebula`
- [Star images](https://github.com/azeem07112007/cosmera/tree/main/dataset/stars): Dataset class · `dataset/stars`
- [Asteroid images](https://github.com/azeem07112007/cosmera/tree/main/dataset/asteroids): Dataset class · `dataset/asteroids`

### External AI

- **Lumina assistant**: NVIDIA NIM / Llama 3 · Generates astronomy explanations, follow-ups, and comparisons.
- **NVIDIA API key**: Credential · Supplied outside tracked source.

## Connections

- Landing page → FastAPI orchestration: served by
- Identify experience → FastAPI orchestration: image upload and chat
- Comparison experience → FastAPI orchestration: two-image comparison
- Learning content → FastAPI orchestration: served by
- Interactive visuals → Identify experience: interactive UI
- Cosmic styling → Identify experience: visual presentation
- FastAPI orchestration → CNN inference: classification request
- CNN inference → Class labels: maps output
- FastAPI orchestration → Lumina assistant: explanations, chat, comparison
- CNN inference → Lumina assistant: classification context
- NVIDIA API key → Lumina assistant: authenticates API access
- Galaxy images → CNN training: labeled training images
- Nebula images → CNN training: labeled training images
- Star images → CNN training: labeled training images
- Asteroid images → CNN training: labeled training images
- CNN training → CNN inference: trained CNN
- CNN training → Class labels: class contract