diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index f30a30f..c80ce4c 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -119,28 +119,26 @@ pub const RateLimitConfig = struct {
 
 ### Cache
 
-**Single-layer cache with two storage backends:**
+**Single layer, two-tier cache system (L1 memory + L2 file):**
 
 **Interface:**
 ```zig
 pub const Cache = struct {
-    lru: LRU,
-    file_store: FileStore,
+    lru: Lru,                    // L1: In-memory cache
+    cache_dir: ?[]const u8,      // L2: Optional file-backed storage
 
     pub fn get(self: *Cache, key: []const u8) ?[]const u8;
     pub fn put(self: *Cache, key: []const u8, value: []const u8, ttl: u64) !void;
 };
 ```
 
-**Cache Key:**
-```
-{user_agent}:{path}:{query}:{client_ip}
-```
-
 **Storage Strategy:**
-- Small responses (<1KB): In-memory LRU only
-- Large responses (≥1KB): LRU stores file path, data on disk
-- TTL: 1000-2000s (randomized to prevent thundering herd)
+- **L1 (Memory)**: LRU cache with configurable max entries
+- **L2 (Disk)**: Optional file-backed storage for persistence
+  - Files stored as JSON with key, value, and expiration timestamp
+  - On eviction from L1, data remains in L2
+  - On cache miss in L1, checks L2 and promotes to L1 if found
+- **TTL**: 1000-2000s (randomized to prevent thundering herd)
 
 **Cache Locations:**
 
@@ -148,23 +146,32 @@ All caches default to `$XDG_CACHE_HOME/wttr` (typically `~/.cache/wttr`).
 
 1. **Weather Response Cache**
    - Location: `$WTTR_CACHE_DIR` (default: `~/.cache/wttr/`)
+   - Format: JSON (one file for each entry/location)
    - Size: 10,000 entries (configurable via `WTTR_CACHE_SIZE`)
    - Expiration: 1000-2000 seconds (randomized)
    - Eviction: LRU
+   - Implementation: `src/cache/Cache.zig`, `src/cache/Lru.zig`
 
 2. **Geocoding Cache**
+   - Purpose: Caches results from nominatim API to minimize API calls
    - Location: `$WTTR_GEOCACHE_FILE` (default: `~/.cache/wttr/geocache.json`)
-   - Format: JSON
+   - Format: JSON (single file with all entries)
    - Expiration: None (persists indefinitely)
+   - Implementation: `src/location/GeoCache.zig`
 
 3. **IP2Location Cache**
+   - Purpose: Caches results from IP2Location.io API to minimize API calls
    - Location: `$IP2LOCATION_CACHE_FILE` (default: `~/.cache/wttr/ip2location.cache`)
-   - Format: Binary (32-byte records)
+   - Format: Text file with header `#Ip2location:v2` followed by CSV lines: `ip,lat,lon,name`
+     Note that name stored at the end so any bytes are included, including commas
    - Expiration: None (persists indefinitely)
+   - Storage: In-memory hash map (u128 IP → Location) + append-only file
+   - Implementation: `src/location/Ip2location.zig` (internal Cache struct)
 
 4. **GeoIP Database**
    - Location: `$WTTR_GEOLITE_PATH` (default: `~/.cache/wttr/GeoLite2-City.mmdb`)
    - Auto-downloaded if missing
+   - Implementation: `src/location/GeoLite2.zig`
 
 ### Location Resolver (`src/location/resolver.zig`)