252627-bhif-syp/terranova

1. Overall shape

- TerraNova is a three-part monorepo: a React/Vite frontend, an ASP.NET Core backend, and a small Node-based geospatial service.

- The product goal, from the README, is an interactive climate-learning platform centered on a 3D globe, country exploration, scenario sliders, and AI-assisted quizzes.

2. Frontend as the main user-facing subsystem

- terranova/frontend is the presentation layer, built with TypeScript + React and bundled with Vite.

- App.tsx, main.tsx, and the components/ tree show a componentized UI split into areas like:

- globe visualization (GlobeScene)

- country info overlays/popups (CountryPopup, LanguageFamilyPopup)

- climate narrative panels (ClimateInsightPanel)

- authentication/account UI (AuthModal, AccountPage, UserMenu)

- quiz UX (Quiz/*)

- State is shared through React contexts such as AuthContext and GlobeContext, which are the main client-side coordination points.

3. Client-side data-heavy visualization

- A large portion of the climate and geography content is shipped as static files under frontend/public/data and frontend/src/data.

- This includes GeoJSON, JSON timelines, scenario datasets, species/red-list tables, and historical climate series.

- Architecturally, this means many visualizations are likely data-driven in the browser, with the frontend reading preprocessed assets rather than requesting every chart or map layer from the backend.

4. Data preprocessing and content pipeline

- The frontend contains scripts under frontend/scripts/ for transforming climate and biodiversity datasets before they are served.

- There is also a root fetch_languages.mjs, suggesting some content is generated or refreshed outside the app runtime.

- This creates a clear boundary between offline/prebuild data preparation and runtime UI rendering.

5. Backend API layer

- terranova/backend/TerraNova.Api is an ASP.NET Core Minimal API app exposing the server-side entry points.

- The endpoint groups are explicitly separated by domain:

- AuthEndpoints

- ChatEndpoints

- CountriesEndpoints

- QuizEndpoints

- TeamEndpoints

- UnsplashEndpoints

- This suggests the backend is the orchestration layer for identity, AI/chat, country metadata, quiz persistence, team/community features, and external image lookup.

6. Core domain boundary

- TerraNova.Core holds the shared domain contracts:

- models like Country, Quiz, Question, QuizResult, User, ChatRequest, ChatResponse

- service interfaces like IChatService and IJwtService

- This is the architecture boundary that keeps business concepts independent from web, database, or third-party implementation details.

7. Infrastructure and persistence

- TerraNova.Infrastructure contains the concrete integrations:

- ApplicationDbContext for Entity Framework Core

- DbSeeder for initial data

- EF migrations for evolving the schema

- service implementations like JwtService, GeminiChatService, and UnsplashService

- The migration history indicates the backend persists structured application data such as users, quizzes, and quiz results in a relational database, likely PostgreSQL given the K8s manifest naming.

8. External service integrations

- The backend is the integration point for external APIs:

- Gemini via GeminiChatService for AI-driven chat or quiz generation

- Unsplash via UnsplashService for image content

- JWT for authentication tokens

- These integrations are isolated behind interfaces, so the API layer depends on stable contracts rather than vendor-specific code.

9. Geospatial auxiliary service

- terranova/gee-service is a separate Node.js service with its own Dockerfile and server.js.

- Given the name and the repository’s globe/climate focus, it likely acts as a specialized service for geospatial/earth-engine-style processing or map-related requests.

- Its separate deployment indicates it is treated as an independent runtime boundary, not just a library.

10. Deployment and runtime topology

- The repo includes both docker-compose.yml and Kubernetes manifests under k8s/.

- Kubernetes resources are split by subsystem: frontend, backend, gee-service, plus backend PostgreSQL and ingress.

- This means the production architecture is containerized and routed through an ingress, with each service deployed independently.

11. How requests flow through the system

- The browser loads the React frontend, which reads static climate/geography datasets locally for fast visualization.

- When the user authenticates, asks AI questions, saves quiz progress, or fetches country/team data, the frontend calls the ASP.NET API.

- The API then:

- validates/authenticates with JWT

- reads/writes application data through EF Core

- forwards AI/image requests to Gemini or Unsplash

- optionally coordinates with the geospatial service for specialized map data

12. Supporting assets and project documentation

- The Docs/ folder contains personas, research, user stories, testing feedback, and vector DB research, which shows the repo is both a product implementation and an evolving project definition.

- The .agents/skills directory is developer tooling/documentation for consistent implementation patterns, but it does not change runtime architecture.