🌌 HOLOCRON ANALYTICS

"Where the Force of Data Meets the Wisdom of the Galaxy"

📑 Table of Contents

• 📜 Overview
• 📂 Project Structure
• 🏗️ Architecture and Performance Engineering
• 🛠️ Engineering Behind the Scenes (Deep Dive)
• 🗺️ Navigation and Features
• 🔗 Integration & Data Protocols (End-to-End)
• 📚 Technical Documentation (Deep Dive)
  • 🤖 AI & NLP Engineering
  • 🎮 Gamification Mechanics
  • 🚀 Production Deploy Guide
  • 🎨 UX & Frontend Architecture
  • 📐 Quality Assurance & Data Architecture
• 🛡️ Infrastructure & Security (DevSecOps)
• 🔌 API Reference (Endpoints)
• 🎨 Design System
• 📋 Environment Variables
• 💻 Detailed Tech Stack
• 🚀 How to Run
• 👨‍💻 Developer

📜 Overview

Holocron Analytics is an immersive and gamified platform built to explore the Star Wars universe. Far beyond a simple wiki, this project turns querying data from the public API (SWAPI) into a “Jedi Archivist” experience, using Artificial Intelligence (OpenAI GPT-4o) to enrich data, generate dynamic quizzes, and simulate interactions with Master Yoda.

Key Features

• 🔍 Digital Holocron: Advanced lookup for Characters, Films, Starships, Planets, Species, and Vehicles.
• 🤖 Master Yoda AI: An integrated LLM-powered chatbot that answers questions about the galaxy with the iconic Jedi Master’s personality, using cached data for ultra-fast responses.
• ⚔️ Gamification & Jedi Trials: A progression system where users climb ranks (Padawan -> Master) by completing challenges and quizzes.
• 📊 Visual Reports: Detailed charts on species distribution, vehicles per film, and galaxy statistics.
• 🚀 Extreme Performance: Advanced caching and background-loading strategies for instant navigation.
• 📱 Responsive Design: Fully adaptive UI for desktop, tablet, and mobile with high-end UX.

📂 Project Structure

Star-Wars-App/
├── backend/                          # FastAPI API (Python)
│   ├── src/app/
│   │   ├── application/              # Application Layer (Use Cases)
│   │   │   └── services/             # Business services
│   │   │       ├── chat_service.py          # AI chat engine
│   │   │       ├── gamification_service.py  # XP and achievements system
│   │   │       ├── quiz_service.py          # AI quiz generation
│   │   │       └── rag_search.py            # Hybrid search engine (RAG)
│   │   ├── domain/                   # Domain Layer (DDD)
│   │   │   ├── entities/             # Business entities
│   │   │   ├── enums/                # Enumerations (JediRank, etc.)
│   │   │   ├── exceptions/           # Custom exceptions
│   │   │   ├── repositories/         # Repository interfaces
│   │   │   └── schemas/              # Pydantic schemas (DTOs)
│   │   ├── infrastructure/           # Infrastructure Layer
│   │   │   ├── cache/                # In-memory cache system
│   │   │   ├── config/               # Settings/config
│   │   │   ├── db/                   # SQLAlchemy models and connection
│   │   │   ├── external/             # External integrations
│   │   │   │   ├── openai/           # OpenAI client (GPT-4o)
│   │   │   │   └── swapi/            # SWAPI client
│   │   │   ├── security/             # JWT, auth handlers
│   │   │   └── etag_middleware.py    # HTTP cache middleware
│   │   └── interfaces/               # Interface Layer
│   │       └── api/v1/
│   │           ├── routers/          # API endpoints
│   │           │   ├── auth.py              # Google OAuth authentication
│   │           │   ├── characters.py        # Characters CRUD
│   │           │   ├── chat.py              # AI chat
│   │           │   ├── films.py             # Films CRUD
│   │           │   ├── gamification.py      # XP, Rank, Achievements
│   │           │   ├── health.py            # Health check
│   │           │   ├── image_fallbacks.py   # Image management
│   │           │   ├── metadata.py          # Metadata for filters
│   │           │   ├── planets.py           # Planets CRUD
│   │           │   ├── species.py           # Species CRUD
│   │           │   ├── starships.py         # Starships CRUD
│   │           │   └── vehicles.py          # Vehicles CRUD
│   │           └── dependencies/     # Dependency injection
│   ├── alembic/                      # DB migrations
│   │   └── versions/                 # Migration scripts
│   ├── tests/                        # Unit tests (Pytest)
│   ├── Dockerfile.cloud-run          # Production Dockerfile
│   ├── Dockerfile.dev                # Development Dockerfile
│   └── pyproject.toml                # Python deps (Poetry)
│
├── frontend/                         # React SPA (TypeScript)
│   ├── src/
│   │   ├── App/                      # Root component and navigation
│   │   ├── features/                 # Domain modules (Feature-based)
│   │   │   ├── auth/                 # Google authentication
│   │   │   │   ├── components/       # UserMenu, LoginButton
│   │   │   │   ├── context/          # AuthProvider, AuthContext
│   │   │   │   ├── pages/            # LoginPage, AuthLoadingPage
│   │   │   │   └── services/         # authService (API calls)
│   │   │   ├── characters/           # Characters module
│   │   │   │   ├── components/       # CharacterCard, CharacterModal
│   │   │   │   ├── hooks/            # useCharacters, useCharacterDetails
│   │   │   │   ├── pages/            # CharactersPage
│   │   │   │   └── services/         # charactersService
│   │   │   ├── chat/                 # AI Chat module
│   │   │   │   ├── components/       # YodaChatBubble, ChatModal
│   │   │   │   ├── context/          # ChatProvider
│   │   │   │   └── hooks/            # useChat, useChatHistory
│   │   │   ├── dashboard/            # Main dashboard
│   │   │   ├── films/                # Films module
│   │   │   ├── gamification/         # Gamification module
│   │   │   │   ├── components/       # QuizModal, AchievementCard
│   │   │   │   ├── hooks/            # useGamification, useQuiz
│   │   │   │   └── pages/            # GamificationPage
│   │   │   ├── planets/              # Planets module
│   │   │   ├── reports/              # Reports module
│   │   │   │   ├── components/       # Charts, LeaderboardTable
│   │   │   │   └── pages/            # ReportsPage
│   │   │   ├── species/              # Species module
│   │   │   ├── starships/            # Starships module
│   │   │   └── vehicles/             # Vehicles module
│   │   └── shared/                   # Shared code
│   │       ├── components/           # Reusable components
│   │       │   ├── CustomSelect/     # Custom Star Wars select
│   │       │   ├── FilmFilter/       # Global film filter
│   │       │   ├── PageLayout/       # Base page layout
│   │       │   ├── Pagination/       # Responsive pagination
│   │       │   ├── ScrollToTop/      # Back-to-top button
│   │       │   └── StarfieldEvents/  # Animated background
│   │       ├── hooks/                # Shared hooks
│   │       │   ├── useFilmOptions.ts        # Film options
│   │       │   ├── useMetadataOptions.ts    # Metadata for filters
│   │       │   └── usePrefetchAllData.ts    # 6-phase prefetch
│   │       ├── services/             # Shared services
│   │       │   ├── api.ts                   # Base HTTP client
│   │       │   └── metadata.service.ts      # Metadata service
│   │       ├── stores/               # Zustand stores
│   │       └── styles/               # Global styles
│   │           └── global.css        # CSS Variables, Starfield
│   ├── api/                          # Vercel Serverless Functions
│   ├── index.html                    # HTML entry point
│   ├── vite.config.ts                # Vite config
│   └── package.json                  # Node.js dependencies
│
├── regras-desenvolvimento-python-react/  # Standards documentation
│   ├── regras-backend.md             # Python/FastAPI standards
│   ├── regras-frontend.md            # React/TypeScript standards
│   └── regras-testes.md              # Testing standards
│
├── docker-compose.dev.yml            # Development compose
├── deploy-starwars.ps1               # GCP deploy script
└── README.md                         # This documentation

🏗️ Architecture and Performance Engineering

The solution was designed with an obsessive focus on performance and fluid UX, using an intelligent loading strategy and multi-level caching.

%%{title: "Performance and Cache Strategy"}%%
flowchart TD
    Init["🚀 App Initialization"] --> FastLoad["🔥 Critical Load"]
    FastLoad --> Render["🖥️ Immediate Render (Optimized LCP)"]
    
    Render --> Background["⏳ Background Loading"]
    Background --> FetchAll["📡 Massive Fetch from SWAPI"]
    FetchAll --> Process["⚙️ Processing & Enrichment"]
    Process --> Cache["💾 Local Cache (Memory)"]
    
    subgraph UX_Fluidity ["Smooth Navigation"]
        UserAction["🖱️ User Navigation"]
        UserAction -- "Data already in Cache" --> InstantServe["⚡ Instant Display"]
        UserAction -- "Chat/Quiz" --> ContextAware["🧠 Preloaded Context"]
    end
    
    Cache -.-> UX_Fluidity

🧠 Artificial Intelligence Pipeline

The AI integration is not just a “wrapper”. It actively fills data gaps and generates content.

%%{title: "AI Data Enrichment Pipeline"}%%
sequenceDiagram
    participant C as Client
    participant B as Backend
    participant DB as Database
    participant SW as SWAPI
    participant AI as Vertex AI (Gemini)

    C->>B: GET /characters/1 (Luke Skywalker)
    B->>DB: Lookup Local Cache
    
    alt Incomplete or Missing Data
        B->>SW: Fetch Basic Data
        SW-->>B: Raw JSON (SWAPI)
        B->>AI: Prompt: "Generate RPG stats for Luke"
        AI-->>B: Enriched JSON (Force: 85, Agility: 80...)
        B->>DB: Save/Update Record
    end
    
    B-->>C: Return Full Character + Stats

🛠️ Engineering Behind the Scenes (Deep Dive)

What sets Holocron Analytics apart is the attention to “invisible” technical details that make the experience magical.

1. 🔍 Search Optimization (NLP & RAG)

The search system (rag_search.py) implements a Retrieval-Augmented Generation engine that understands native Portuguese.

• Hybrid Fuzzy Search: Uses rapidfuzz (Levenshtein Distance) to correct typos ("Anakin Skywaler" -> Finds "Anakin Skywalker").
• PT-BR Stemming: A custom algorithm that removes suffixes (-inho, -mente, -ão) to understand search intent.
• Entity Detection: Smart heuristics distinguish when the user searches for a droid ("R2") vs. a generic term, avoiding false positives.
• Synonyms: Automatically maps terms like "sabre de luz" ↔ "lightsaber" or "robô" ↔ "droid".

2. 🧙 Persona Engineering (Prompting)

Master Yoda AI is not just a standard chatbot.

• Dynamic Context: The system injects official SWAPI data snippets into the model context to keep answers factual (Grounding), reducing hallucinations.
• Syntactic Inversion: The system prompt instructs the AI to mimic Yoda’s unique grammar (Object-Subject-Verb).
• Multiple Personas: The architecture supports persona switching, also enabling a "Darth Vader" persona that responds with hostility and forbidden emojis.

3. ✨ Cinematic Frontend

The UI was built for total immersion:

• Dynamic Starfield: The star background (StarfieldEvents.tsx) is not a looping video. It’s a procedurally-generated particle system simulating “space traffic”, with meteors varying in speed, angle, and depth.
• Accessibility: The system detects the OS prefers-reduced-motion preference and automatically disables heavy animations for motion-sensitive users.

🗺️ Navigation and Features

1. 🔍 Holocron (Data Exploration)

Dedicated pages for each Star Wars entity, with rich, interactive cards.

• Pages: Characters, Films, Starships, Planets, Species, Vehicles.
• Advanced Filters:
  • Filter by Name, Gender, Climate (Planets), Class (Starships), and more.
  • Fuzzy (approximate) search to find terms even with typos.
  • Dynamic sorting and instant pagination (client-side pagination thanks to preloading).

2. 📊 Reports and Analytics

Located in the reports folder, this section provides visual insights through interactive charts.

• Species Distribution: Pie/bar charts showing the diversity of the galaxy.
• Starship Comparison: Scatter plots comparing speed vs. cost.
• Timeline: Visual timeline of films and events.

3. ⚔️ Full Gamification

The system keeps users engaged through a levels and rewards system.

• Jedi Trials: AI-generated quizzes that test knowledge.
• XP Bar: Earn experience by exploring the system, completing quizzes, and discovering “easter eggs”.
• Rankings: Start as Youngling, become Initiate, Padawan, Knight, and finally Jedi Master.
• Achievements: Unlockable badges (e.g., "Visited all planets", "Answered 10 questions in a row").

4. ⚡ Phased Loading Strategy (6-Phases Prefetch)

To ensure an “instant” experience, the frontend (usePrefetchAllData.ts) implements a 6-stage hydration pipeline that runs silently in the background:

1. Phase 1 (Critical): Dashboard (LCP). Loads data for Home.
2. Phase 2 (Navigation): First 3 pages of ALL listings (Characters, Starships, etc).
3. Phase 3 (Rich Content): Full details of all films.
4. Phase 4 (Big Data): Loads massive datasets (100+ items) to generate the Reports charts.
5. Phase 5 (Social): User profile, achievements, leaderboard, and daily challenges.
6. Phase 6 (Bulk Quiz): Downloads hundreds of potential questions so Jedi Trials works offline/without delay.

All of this happens without blocking the main thread, using setTimeout and React Query priority management.

5. 🛡️ Intelligent Cache Middleware

The backend does not rely only on the browser. We implemented a Global ETag Middleware (etag_middleware.py) that:

• Intercepts all JSON responses.
• Generates a SHA-256 hash of the content.
• Compares it with the request’s If-None-Match header.
• Returns 304 Not Modified (0 bytes body) if data hasn’t changed, saving bandwidth and client processing.

6. 🖼️ Image Lookup & Fallback Strategy

SWAPI does not provide images. ImageLookupService implements a layered resolution strategy:

1. Databank Index: Tries to match the resource name against an image index extracted from the official Star Wars Databank.
2. Legacy Fallback: If it fails, it looks up a local table (image_fallbacks) manually mapped for obscure items.
3. Conservative Matching: Uses string normalization algorithms (casefold + strip) to ensure "X-Wing" matches "x-wing fighter", but returns None if there’s no absolute certainty (avoiding wrong images).

7. 📑 Abstract Pagination (SWAPI Slicing)

SWAPI enforces pagination of 10 items. The frontend needs grids of 12, 8, or 100 items. The swapi_pagination.py module solves this with Virtual Slicing:

• Mathematically computes which SWAPI pages (e.g., page 3 and 4) contain the desired slice (e.g., items 25 to 36).
• Fetches only the required pages in parallel (asyncio.gather).
• Combines results and slices the exact array for the client.
• Result: The frontend can request pageSize=100 and the backend transparently orchestrates 10 parallel SWAPI calls.

8. 🎮 Gamification Engine (Jedi Trials)

The engagement system (gamification_service.py) is not just a points counter.

• Behavioral Achievements: Achievements like "Friend of Yoda" or "Vader’s Minion" are unlocked by analyzing interaction history with specific personas (chat_stats_by_persona).
• Live XP & Ranks: Level calculation is instant, using a progression curve based on cumulative XP (Youngling $\to$ Padawan $\to$ Knight $\to$ Master).
• Leaderboard Aggregation: Optimized SQL queries aggregate complex statistics in real time, computing accuracy (% correct) and best quiz sessions for the global leaderboard.

🔗 Integration & Data Protocols (End-to-End)

The SWAPI communication architecture was designed to be resilient and invisible to the end user. Below is the full request flow.

1. Client Protocol (SWAPIClient)

SWAPIClient (src/app/infrastructure/external/swapi/client.py) acts as an intelligent gateway:

• HTTP Keep-Alive: Uses httpx.AsyncClient to keep persistent connections, reducing TCP/TLS handshake overhead across multiple requests.
• Transparent Pagination: _paginate_all abstracts the API next cursor logic, automatically iterating until it consumes all data when needed (e.g., for reports).
• URL Normalization: The client normalizes URLs and IDs automatically, ensuring https://swapi.dev/api/people/1/ and https://swapi.dev/api/people/1 are treated as the same cache resource.

2. Data Flow (Sequence Diagram)

The diagram below illustrates the path of a simple request (e.g., "List Starships") and how the system chooses between Cache, External API, and Image Lookup.

sequenceDiagram
    participant UI as Frontend (React Query)
    participant API as FastAPI Backend
    participant Cache as Memory Cache (TTL)
    participant SWAPI as SWAPI.dev
    participant DB as PostgreSQL (Images Setup)

    UI->>API: GET /starships?page=1&pageSize=12
    API->>Cache: GET swapi:starships:page:1
    
    alt Cache Miss (First Access)
        API->>SWAPI: GET /starships/?page=1 & page=2 (Parallel)
        SWAPI-->>API: JSON Raw Data
        
        API->>DB: Resolve Image URLs (Virtual Join)
        DB-->>API: Starship URLs
        
        API->>API: Normalize Data (snake_case, numbers)
        API->>Cache: SET swapi:starships:page:1 (TTL 1h)
        API-->>UI: Optimized JSON + Images
    else Cache Hit
        Cache-->>API: Ready Data
        API-->>UI: Instant Response (<10ms)
    end

3. Data Handling and Normalization

SWAPI returns “dirty” data by modern standards (strings for numbers, mixed snake_case). StarWarsApp implements a Data Sanitization layer:

• Number Parsing: parse_swapi_number converts complex strings like "unknown", "n/a", or ranges "30-165" into safe numeric types (Optional[float]) to enable correct sorting and charts.
• Date Standardization: All dates are converted to strict ISO-8601.
• Cross-Reference Resolving: Relationship URLs (e.g., pilots: [...]) are kept as references but prepared for lazy loading in the frontend.

4. 🔐 Secure Authentication Protocol (JWT + Cookie)

We implemented the Silent Refresh pattern for maximum security:

• Access Token: Short-lived (15min), stored in memory (JavaScript), used as a Bearer Token.
• Refresh Token: Long-lived (7 days), stored in an HttpOnly Cookie (Secure, SameSite), inaccessible via JS.
• Token Rotation: On each refresh, the previous token is invalidated and a new one is issued, preventing replay attacks.

sequenceDiagram
    participant U as User
    participant F as Frontend
    participant B as Backend
    participant D as Database
    
    U->>F: Login with Google
    F->>B: Send Google Credential
    B->>D: Verify/Create User
    B-->>F: Return Access Token + User Info
    B-->>U: Set-Cookie: refresh_token (HttpOnly)
    
    Note over F,B: Secure Navigation
    
    F->>B: GET /api/v1/characters (Bearer Access)
    B-->>F: 200 OK
    
    Note over F,B: Access Token Expires
    
    F->>B: GET /api/v1/characters
    B-->>F: 401 Unauthorized
    F->>B: POST /auth/refresh (Automatic Cookie)
    B->>D: Validate Refresh Token
    B-->>F: New Access Token
    B-->>U: Set-Cookie: New refresh_token
    F->>B: Retry Original Request

5. 🤖 Context-Aware Chat Engine (ChatService)

chat_service.py is the brain of the application, orchestrating over 2,000 lines of conditional logic and AI.

• Intent Routing: Before calling the LLM, the system analyzes intent with regex heuristics. Example: "Who is Luke?" queries the local DB/SWAPI directly, saving tokens and latency.
• RAG Pipeline:
  1. Extract Entities: Identifies "Luke", "Tatooine" in the sentence.
  2. Hybrid Search: Vector + keyword search in the knowledge base.
  3. Context Injection: Injects JSON snippets (e.g., force stats) into the system prompt.
  4. Persona Tuning: Adjusts the response to the "Yoda" style (syntactic inversion) or "Vader".

📚 Technical Documentation (Deep Dive)

For developers who want to understand internal details, we document all critical subsystems directly here:

flowchart TD
    UserInput["🗣️ User Message"] --> PreProcess["🔧 Pre-processing"]
    PreProcess --> Routing{⚡ Intent Routing}
    
    Routing -- "Regex/Fixed Pattern" --> DirectReply["📝 Direct Reply (No LLM)"]
    Routing -- "Complex Question" --> RAG["🔍 RAG Search (Context Recovery)"]
    
    RAG -- "Data Found" --> ContextInj["💉 Context Injection (JSON)"]
    ContextInj --> PromptEng["🎭 Persona Engineering"]
    PromptEng --> LLM["🤖 AI Invocation"]
    
    LLM --> Response["💬 Final Answer"]
    DirectReply --> Response

SWAPI DATA (factual reference):
{
  "name": "Luke Skywalker",
  "height": "172",
  "mass": "77",
  "hair_color": "blond",
  "skin_color": "fair",
  "eye_color": "blue",
  "birth_year": "19BBY",
  "gender": "male"
}

Rules:
- For attributes present in the data, use the values above as the source of truth.
- Do not invent numbers if they are not here.

# Rule pseudocode
if yoda_messages >= 5: unlock("amigo_yoda")
if vader_messages >= 5: unlock("lacaio_vader")

# Example: Creating the JWT secret
printf "my-super-secret-key" | gcloud secrets create holocron-jwt-secret-key --data-file=-

# Example: Creating the DB secret
printf "db-password" | gcloud secrets create holocron-db-password --data-file=-

.\deploy-starwars.ps1

.\deploy-starwars.ps1 -Region "us-central1"

gcloud run services logs read star-wars-backend

🛡️ Infrastructure & Security (DevSecOps)

Security is not an “add-on”, but part of the cloud-native infrastructure design.

1. 🔑 Secrets Management

We adopted a Zero Hardcoded Secrets strategy.

• Frontend (Vercel): Public keys (Google Client ID) and API URLs are injected at build time via Vercel environment variables. No private key ever touches the client bundle.
• Backend (Google Cloud Run): Critical secrets (DB Password, JWT Secret, OpenAI Key) are managed by GCP Secret Manager. They are mounted into the container as runtime environment variables, ensuring not even the Dockerfile can access them.

2. 🐳 Secure Containerization Pipeline

Dockerfile.cloud-run follows hardening best practices:

• Minimal Base Image: Based on python:3.12-slim to drastically reduce the attack surface (fewer vulnerable binaries).
• Stateless by Design: The container retains no data. Uploads and persistence are delegated to external services (Storage/PostgreSQL).
• Auto-Migrations: The entrypoint runs alembic upgrade head on every deploy, ensuring the DB schema stays synchronized with application code (Infrastructure as Code).

3. 💾 Persistence and Resilience

Although the application heavily relies on cache, PostgreSQL is the source of truth for critical data:

• User Profiles: Sensitive data and gamification progress.
• Image Fallbacks: Our image_fallbacks table acts as a failover system. If the external image CDN fails, the system automatically falls back to curated assets stored in the database.

graph TD
    subgraph "Public Zone (Vercel)"
        Frontend[React SPA]
    end
    
    subgraph "Private Zone (Google Cloud Platform)"
        LB[Load Balancer HTTPS]
        
        subgraph "Cloud Run (Auto-Scaling)"
            API[FastAPI Container]
        end
        
        Secret[GCP Secret Manager]
        DB[(PostgreSQL)]
        Vertex[Vertex AI]
    end
    
    Frontend -- "Bearer JWT (TLS 1.3)" --> LB
    LB --> API
    
    API -- "Env Vars Injection" --> Secret
    API -- "SQLAlchemy (Connection Pool)" --> DB
    API -- "IAM Credentials" --> Vertex
    
    style Secret fill:#f9f,stroke:#333
    style DB fill:#ccf,stroke:#333

9. 🛡️ Compliance & Security Standards (RBAC & OWASP)

The project was audited following strict software security principles, aligned with the OWASP Top 10 and corporate compliance rules.

9.1 Access and Identity (RBAC & Invoker)

• Cloud Run Invoker: The backend is not public. It runs in authenticated-only mode, accepting only requests with a valid Google-signed OIDC token (via Vercel Service Account). No one can access the API directly without going through the frontend.

• RBAC (Role-Based Access Control): Internally, administrative endpoints validate the JWT token. Only authenticated users (require_authenticated_user_id) can persist data or generate complex reports.

9.2 Vulnerability Prevention (OWASP)

9.3 Cloud Run Private Access Diagram

This graph shows how backend access is locked down.

%%{title: "Cloud Run Private Access & API Shielding"}%%
flowchart LR
    subgraph External_World ["External World"]
        User[User]
        Hacker[Attacker]
    end
    
    subgraph Security_Perimeter ["Security Perimeter (Google Auth)"]
        Vercel["Vercel Frontend"]
    end
    
    subgraph Private_Zone ["Private Zone (Secure Backend)"]
        CloudRun["Cloud Run Backend"]
        DB[("PostgreSQL")]
        Secrets["Secret Manager"]
    end
    
    subgraph Shielded_APIs ["External APIs (Shielded)"]
        SWAPI["SWAPI (Data)"]
        AI["OpenAI / Vertex AI"]
    end
    
    %% User flow
    User -- HTTPS --> Vercel
    Hacker -. "Direct Access (403 Forbidden)" .-> CloudRun
    
    %% Service-to-service auth
    Vercel -- "OIDC ID Token (Auth)" --> CloudRun
    
    %% Backend accessing resources
    CloudRun -- "Internal Traffic" --> DB
    CloudRun -- "Load API Keys" --> Secrets
    
    %% Shielding: backend protects keys and rate-limits
    CloudRun -- "Proxied Request" --> SWAPI
    CloudRun -- "Secure Context" --> AI
    
    %% Styling
    style Vercel fill:#000,color:#fff
    style CloudRun fill:#4285F4,color:#fff
    style Hacker stroke:red,stroke-width:2px,stroke-dasharray: 5 5
    style Secrets fill:#FFEB3B,color:#000

🔌 API Reference (Endpoints)

The REST API follows OpenAPI 3.0 standards. Interactive documentation is available at /docs (Swagger UI).

🔐 Authentication (/api/v1/auth)

👤 Characters (/api/v1/characters)

Query Params: page, pageSize, search, gender, homeworld, species, film, sort

🎬 Films (/api/v1/films)

🚀 Starships (/api/v1/starships)

Query Params: page, pageSize, search, starship_class, manufacturer, film, sort

🌍 Planets (/api/v1/planets)

Query Params: page, pageSize, search, climate, terrain, film, sort

👽 Species (/api/v1/species)

Query Params: page, pageSize, search, classification, designation, language, film, sort

🚗 Vehicles (/api/v1/vehicles)

Query Params: page, pageSize, search, vehicle_class, manufacturer, film, sort

🤖 AI Chat (/api/v1/chat)

Body (POST):

{
  "message": "Who is Luke Skywalker?",
  "persona": "yoda"  // or "vader"
}

🎮 Gamification (/api/v1/gamification)

📊 Metadata (/api/v1/metadata)

🖼️ Images (/api/v1/image-fallbacks)

❤️ Health Check (/api/v1/health)

🎨 Design System

The Holocron Analytics UI was designed to deliver an immersive Star Wars experience.

🎨 Color Palette

✨ Visual Effects

• Glassmorphism: Cards with backdrop-filter: blur(12px) and translucent borders.
• Neon Glow: Colored shadows (box-shadow) for interactive elements.
• Dynamic Starfield: Animated background with CSS/JS particles.
• Hover Transitions: Smooth effects with transform and opacity (0.2s ease).

🧩 Reusable Components

🪝 Custom Hooks

📋 Environment Variables

Backend (.env or GCP Secret Manager)

# 🔌 Database
DATABASE_URL=postgresql://user:password@host:5432/dbname

# 🔐 Authentication
JWT_SECRET_KEY=your-256-bit-secret-key
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=15

# 🌐 Google OAuth
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

# 🤖 OpenAI
OPENAI_API_KEY=sk-...
AI_ENABLED=true
OPENAI_MODEL=gpt-4o

# 🔗 CORS
CORS_ALLOW_ORIGINS=http://localhost:5173,https://your-domain.vercel.app

# 📊 Environment
ENVIRONMENT=development  # or production
LOG_LEVEL=INFO

Frontend (.env or Vercel Environment Variables)

# 🔗 API
VITE_API_URL=http://localhost:8000/api/v1

# 🌐 Google OAuth (Public Key)
VITE_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com

# ⚙️ Configuration
VITE_APP_TITLE=Holocron Analytics

💻 Detailed Tech Stack

Backend (Python 3.12)

Frontend (Node.js 20+)

Infrastructure

🚀 How to Run

Prerequisites

• Docker & Docker Compose (Recommended)

Running with Docker

1. At the project root:

   docker-compose -f docker-compose.dev.yml up -d --build
   

2. Access:

   • Frontend: http://localhost:5173
   • Docs: http://localhost:8000/docs

👨‍💻 Developer

Project delivered for the PowerOfData Technical Challenge.

"Do or do not. There is no try." — Master Yoda