# lexx-lazz/lil-guys architecture

> Architecture diagram of the GitHub repository lexx-lazz/lil-guys, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lexx-lazz/lil-guys
- Repository: https://github.com/lexx-lazz/lil-guys

## Overview

#### Purpose and Entry Point
Lil Guys is a small shared virtual-pet care application. Users anonymously join a common pet collection, adopt pets, feed them, and observe synchronized happiness changes. The browser entry point is `index.html`; it contains the UI, client-side behavior, styling integration, and Firebase interaction.

#### Client Application Shell
`index.html` is the application’s primary runtime boundary: it renders the responsive pet-management interface and executes the JavaScript needed for adoption, selection, feeding, cooldown visualization, mood display, and speech bubbles. Tailwind CSS is used for presentation, likely loaded or configured directly from this single-page entry.

#### Identity and Shared Access
Firebase Authentication provides anonymous sign-in so each browser can access the shared application without account setup. Firebase project selection and deployment aliases are defined in `.firebaserc`; the Firebase hosting/runtime configuration is in `firebase.json`.

#### Real-Time Pet State
Cloud Firestore is the authoritative shared state store. The client reads pet records in real time and writes adoption/feed updates, allowing every connected participant to observe the same list and changing happiness values. Firestore query/index requirements are captured in `firestore.indexes.json`.

#### Pet-Care Domain Behavior
The browser-side domain logic manages:
- Pet type and name creation during adoption.
- Food preference effects that raise or lower happiness.
- Feeding cooldown/“chewing” state and its visual meter.
- Happiness decay on a 12-hour cadence.
- Mood-derived happiness bars, emoji, and periodically displayed speech bubbles.

This logic is client-driven but persists shared outcomes through Firestore, making database updates the synchronization boundary.

#### Security and Deployment Boundaries
Firestore access policy is enforced independently of the browser by `firestore.rules`, which should constrain anonymous users to the intended shared-pet operations. Firebase Hosting deployment and other Firebase service settings are defined by `firebase.json`; `.firebaserc` selects the target Firebase project.

#### Primary Flow
1. Browser loads `index.html`.
2. Client anonymously authenticates with Firebase.
3. Client subscribes to Firestore pet data and renders the shared collection.
4. User adopts or feeds a selected pet; client calculates local domain effects and writes updated state.
5. Firestore propagates updates to all subscribed clients.
6. Client continuously derives UI state such as cooldown progress, happiness decay eligibility, mood, and speech from pet records and time.

Main entry points: [`index.html`](https://github.com/lexx-lazz/lil-guys/blob/master/index.html) (Pet App Shell), [`firebase.json`](https://github.com/lexx-lazz/lil-guys/blob/master/firebase.json) (Firebase Hosting), [`firestore.rules`](https://github.com/lexx-lazz/lil-guys/blob/master/firestore.rules) (Firestore Rules), [`firestore.indexes.json`](https://github.com/lexx-lazz/lil-guys/blob/master/firestore.indexes.json) (Firestore Indexes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser Client"]
  node_browser(("Browser<br/>runtime"))
  node_index["Pet App Shell<br/>single-page client<br/>[index.html]"]
  node_tailwind["Tailwind CSS<br/>presentation<br/>[index.html]"]
  node_identity["Anonymous Identity<br/>client auth state<br/>[index.html]"]
  node_pet_logic["Pet-Care Logic<br/>client domain logic<br/>[index.html]"]
  node_pet_ui["Pet Collection UI<br/>reactive view<br/>[index.html]"]
end

subgraph group_firebase["Firebase Services"]
  node_auth{{"Firebase Authentication<br/>identity service"}}
  node_firestore[("Cloud Firestore<br/>shared state store")]
  node_rules["Firestore Rules<br/>access policy<br/>[firestore.rules]"]
  node_indexes["Firestore Indexes<br/>query indexes"]
  node_hosting{{"Firebase Hosting<br/>deployment runtime<br/>[firebase.json]"}}
  node_firebase_config["Firebase Configuration<br/>service configuration<br/>[firebase.json]"]
  node_project_alias["Firebase Project Alias<br/>deployment target<br/>[.firebaserc]"]
end

node_browser -->|"loads app"| node_hosting
node_hosting -->|"serves"| node_index
node_index -->|"styles with"| node_tailwind
node_index -->|"initializes"| node_identity
node_identity -->|"anonymous sign-in"| node_auth
node_index -->|"runs"| node_pet_logic
node_pet_logic -->|"subscribes and writes"| node_firestore
node_firestore -->|"real-time pet updates"| node_pet_ui
node_pet_logic -->|"derives mood and cooldown UI"| node_pet_ui
node_pet_ui -->|"adopt and feed actions"| node_pet_logic
node_rules -->|"authorizes access"| node_firestore
node_indexes -->|"supports queries"| node_firestore
node_firebase_config -->|"configures"| node_hosting
node_project_alias -->|"selects project"| node_firebase_config

click node_index "https://github.com/lexx-lazz/lil-guys/blob/master/index.html"
click node_tailwind "https://github.com/lexx-lazz/lil-guys/blob/master/index.html"
click node_identity "https://github.com/lexx-lazz/lil-guys/blob/master/index.html"
click node_pet_logic "https://github.com/lexx-lazz/lil-guys/blob/master/index.html"
click node_pet_ui "https://github.com/lexx-lazz/lil-guys/blob/master/index.html"
click node_rules "https://github.com/lexx-lazz/lil-guys/blob/master/firestore.rules"
click node_indexes "https://github.com/lexx-lazz/lil-guys/blob/master/firestore.indexes.json"
click node_hosting "https://github.com/lexx-lazz/lil-guys/blob/master/firebase.json"
click node_firebase_config "https://github.com/lexx-lazz/lil-guys/blob/master/firebase.json"
click node_project_alias "https://github.com/lexx-lazz/lil-guys/blob/master/.firebaserc"

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_browser,node_index,node_tailwind,node_identity,node_pet_logic,node_pet_ui toneBlue
class node_auth,node_firestore,node_rules,node_indexes,node_hosting,node_firebase_config,node_project_alias toneAmber
```

## Components

### Browser Client

Single-page pet-care application.

- **Browser**: runtime
- [Pet App Shell](https://github.com/lexx-lazz/lil-guys/blob/master/index.html): single-page client · Renders the interface and runs all pet-care behavior. · `index.html`
- [Tailwind CSS](https://github.com/lexx-lazz/lil-guys/blob/master/index.html): presentation · `index.html`
- [Anonymous Identity](https://github.com/lexx-lazz/lil-guys/blob/master/index.html): client auth state · `index.html`
- [Pet-Care Logic](https://github.com/lexx-lazz/lil-guys/blob/master/index.html): client domain logic · Adoption, feeding effects, cooldowns, decay, mood, and speech. · `index.html`
- [Pet Collection UI](https://github.com/lexx-lazz/lil-guys/blob/master/index.html): reactive view · Shows selected pets, happiness, mood, cooldowns, and speech. · `index.html`

### Firebase Services

Shared backend, access control, and deployment.

- **Firebase Authentication**: identity service · Provides anonymous sign-in.
- **Cloud Firestore**: shared state store · Authoritative real-time pet records.
- [Firestore Rules](https://github.com/lexx-lazz/lil-guys/blob/master/firestore.rules): access policy · Independently constrains anonymous pet operations. · `firestore.rules`
- [Firestore Indexes](https://github.com/lexx-lazz/lil-guys/blob/master/firestore.indexes.json): query indexes · `firestore.indexes.json`
- [Firebase Hosting](https://github.com/lexx-lazz/lil-guys/blob/master/firebase.json): deployment runtime · Serves the browser application. · `firebase.json`
- [Firebase Configuration](https://github.com/lexx-lazz/lil-guys/blob/master/firebase.json): service configuration · Defines Firebase hosting and runtime settings. · `firebase.json`
- [Firebase Project Alias](https://github.com/lexx-lazz/lil-guys/blob/master/.firebaserc): deployment target · `.firebaserc`

## Connections

- Browser → Firebase Hosting: loads app
- Firebase Hosting → Pet App Shell: serves
- Pet App Shell → Tailwind CSS: styles with
- Pet App Shell → Anonymous Identity: initializes
- Anonymous Identity → Firebase Authentication: anonymous sign-in
- Pet App Shell → Pet-Care Logic: runs
- Pet-Care Logic → Cloud Firestore: subscribes and writes
- Cloud Firestore → Pet Collection UI: real-time pet updates
- Pet-Care Logic → Pet Collection UI: derives mood and cooldown UI
- Pet Collection UI → Pet-Care Logic: adopt and feed actions
- Firestore Rules → Cloud Firestore: authorizes access
- Firestore Indexes → Cloud Firestore: supports queries
- Firebase Configuration → Firebase Hosting: configures
- Firebase Project Alias → Firebase Configuration: selects project