Skip to content

technical-overview.md

Latest commit

 

History

History
80 lines (62 loc) · 3.38 KB

technical-overview.md

File metadata and controls

80 lines (62 loc) · 3.38 KB
Raw

Technical overview for product and recruiting audiences

Back to portfolio

System shape

Solar Village is a server-rendered web game with a browser interaction layer. A Flask service owns routes and initial rendering; a state-machine layer manages the journey; business logic calculates feedback, scoring and personality results; SQLite persists session progress. Vercel hosts the production build as a serverless application.

flowchart TB
    subgraph Client
        UI[HTML/CSS game stage]
        JS[JavaScript interactions]
    end

    subgraph Application
        ROUTES[Flask routes and SSR]
        FSM[Journey state machine]
        RULES[Scoring, feedback and personality rules]
    end

    subgraph Data
        SESSION[(SQLite session state)]
        CONTENT[Season and location content]
        MEDIA[Static visual assets]
    end

    UI <--> JS
    JS <--> ROUTES
    ROUTES --> FSM
    ROUTES --> RULES
    FSM <--> SESSION
    RULES <--> SESSION
    RULES --> CONTENT
    UI --> MEDIA
    RULES -. optional enrichment .-> MODEL[Zhipu-compatible LLM]
Loading

Product-relevant boundaries

Boundary Product reason
State machine vs. presentation Keeps visual transitions from inventing or skipping product state
Scoring path vs. map stamps Separates canonical completion from progress communication
Rules vs. optional LLM Preserves deterministic outcomes and graceful degradation
Content configuration vs. runtime Allows seasonal copy and layout to evolve without scattering hard-coded values
Server entry vs. static assets Makes serverless deployment requirements explicit

Major state domains

  • Screen state: welcome, opening questions, feedback, map, season and personality.
  • Season state: current chapter, active location, conversation phase and emotion step.
  • Progress state: completed locations, play order, choice path and seasonal stamps.
  • Scoring state: personality dimensions, seasonal resonance and tie-breaking context.
  • Presentation state: map markers, stage bounds, result artwork and download behavior.

Serverless considerations

Vercel functions have an ephemeral writable file system. The release therefore uses a temporary database location for runtime state, initializes required schema at startup and relies on signed session snapshots for recovery. Production-critical templates, data modules and static assets are explicitly included in deployment configuration.

Reliability principles

  1. One canonical rule answers whether the complete journey is ready for personality evaluation.
  2. State healing may normalize existing answers but must never manufacture product progress.
  3. APIs should be idempotent at terminal phases so repeated clicks or retries do not double-advance.
  4. Missing optional services must produce a controlled fallback, not a dead end.
  5. Cross-layer rules belong in shared modules and documentation, not duplicated browser conditions.

Technology snapshot

Area Technology
Application Python, Flask
Browser layer HTML, CSS, JavaScript
Persistence SQLite session store
Deployment Vercel Serverless
Optional AI Zhipu-compatible provider and model configuration
Quality Python regression suites, JavaScript syntax checks, online end-to-end probes

This document intentionally omits private implementation details and source excerpts.