From 6cf39d2672ca796f15236fbc6f7148c1d750a0ca Mon Sep 17 00:00:00 2001 From: Hyperling Date: Wed, 19 Aug 2026 12:18:30 -0700 Subject: [PATCH] Lots of DB content as well as some love to the frontend and fetcher sections. --- Design.md | 229 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 220 insertions(+), 9 deletions(-) diff --git a/Design.md b/Design.md index dbfd326..8121e75 100644 --- a/Design.md +++ b/Design.md @@ -34,19 +34,71 @@ Developer: Hyperling Language/Framework: Flutter +### Planned Versions + +**0.1** +: Basic listview app, hardcode limited production API key. + +**0.2** +: Change main page to a Celtic Wheel type layout with season signifier. + +**1.0** +: Integrate with a backend cache server which provides aggregated data. + +**1.1** +: Add settings page and other nice to haves. + +### Requirements + +- App shall start with a Main page only, then have a Settings page added later. +- App shall come with a limited use API key. This key shall not be used by any +other module of this project. Developers should use their seperate API key when +using Postman, testing the Weather Fetcher, etc. + +### Pages + +#### Main + +*Initial Versions - Simple Data Entry* + +--- + +8 sections which contain (three?) data input fieldss: + +- Zip Code +- Lat & Long (or should the lat/long just be used to lookup the zip code?) +- Nickname + +*Formal Versions - Wheel Layout* + +--- + +Circular layout representing the Celtic season wheel with 'LAST_UPDATE_DATE' +in the center so the user knows when the highs and lows were last refreshed. + +"Hand" which points to the current season. Accurate to the day preferably, so +if we're at September 1 it's pointing in between Summer CQ and Fall Equinox. + +- Initially can just highlight the current half quarter and start making the next +one glow as it gets approached. So for June 21, Spring2 and Summer1 would both +glow at 50% since that's the day they transition. Then by mid July it would only +be Summer1 which glows, and at the end of July Summer1 would be dim and Summer2 +would be glowing more. + #### Settings **Not required in initial versions of the app, focus on pulling data first!** -1. Server +1. 'Server' - Toggle: 'Use Cache Server' - TRUE: - Radio Group: 'Aggregation Mode' - - 'Mean / Average' - - 'Mode / Most Common' - - 'Median / Center-Most' - - 'Today Only' - - 'Tomorrow Only' + - 'Week : Mean / Average' + - 'Week : Median / Center-Most' + - 'Week : Mode / Most Common' + - 'Only : Today' + - ?'Only : Tomorrow' + - ?'Only : Today + 7' - FALSE: - TextEdit: 'API Key' (REQUIRED) - 'If not using the cache server, you'll need to provide your own API key for TBD weather service.' @@ -66,27 +118,186 @@ Language/Framework: Flutter - Greather Than - Checkbox: 'Equal To' - ### Description ### Requirements ## 2. Database - - ### Description ### Requirements +- All temperature data shall be stored in Fahrenheit. Decimals are okay. +- All date data shall be displayed as 'YYYY-MM-DDTHH24:MI:SS' GMT +(or 'YYYY-MM-DDTHH24:MI:SS+0000') in any reporting or data transfers. Time zones +will be handled at the frontend. The 'T' in the center is a dead character. Example: + ```shell + $ echo "Actual Time: `date`" && echo "Report Time: `date -u +'%Y-%m-%dT%H:%M:%S%z'`" + Actual Time: Wed Aug 19 10:49:52 AM MST 2026 + Report Time: 2026-08-19T17:49:52+0000 + ``` +- Database shall be set to case insensitive, so that `SELECT column FROM loc` +and `select COLUMN from LOC` are the same command. +- Database shall have a daily purge script followed by statistics rebuilding. +The records to be removed will look like (TBD: `IS_PURGED = true`). The purge +will cascade through any child tables. Bonus points if they exist, are scheduled, +and gets executed from inside the DB rather than needing to run outside files. +- Database object script(s) for the primary initialization as well as patches +shall be reproducible and rerunnable, meaning they drop then create all database +objects, constraints, schedules, etc being added in the revision. Example: + ```sql + -- Undo Section -- + -- Allowed to have failures if the objects don't exist yet. + SET ERRORS OFF / ON ERROR CONTINUE / ETC; + DROP TABLE example_child; + DROP TABLE example; + + -- Apply Section -- + -- All commands must succeed successfully in order to continue. + SET ERRORS ON / ON ERROR EXIT / ETC; + CREATE TABLE example + ( example_id INT PRIMARY KEY + , example_data VARCHAR + ); + CREATE TABLE example_child + ( example_child_id INT PRIMARY KEY + , example_id INT FOREIGN KEY (example.example_id) + , more_example_data VARCHAR + ); + ``` +- Scripts shall have a consistent style and formatting. Developer may use the +style of their choice. + +### Tables + +- Database and schema names shall be short and easy to remember, otherwise they +are the developer's choice. Bonus points if the DB does not require them to +access the tables, or a setting / parameter can be set to default to them. + ```sql + -- yucky + select * from db_name.schema_name.table_name; + -- preferred + select * from table_name; + ``` + +#### Table 1: `loc` + +| Column Name | Type | Constraints | Calculated? | +| --- | :-: | :---: | :-----: | +| loc_id | INT | PK | - | +| zip_code | STRING | UNIQUE | - | +| last_accessed_date | DATE | - | - | +| needs_purged | - | - | CASE WHEN sysdate < last_accessed_date + 90 THEN true ELSE false ESAC | + +#### Table 3: `loc_weather_agg` + +| Column Name | Type | Constraints | Calculated? | +| --- | :-: | :---: | :-----: | +| loc_weather_agg_id | INT | PK | - | +| loc_weather_id | INT | FK (loc_weather.loc_weather_id) | - | +| weekly_mean_high | DECIMAL | - | - | +| weekly_mean_low | DECIMAL | - | - | +| weekly_median_high | DECIMAL | - | - | +| weekly_median_low | DECIMAL | - | - | +| weekly_mode_high | DECIMAL | - | - | +| weekly_mode_low | DECIMAL | - | - | +| tomorrow_high | DECIMAL | - | - | +| tomorrow_low | DECIMAL | - | - | +| extended_high | DECIMAL | - | - | +| extended_low | DECIMAL | - | - | + +Today's high and low are accessible when joining to the `LOC_WEATHER` table, which +is necessary anyways to get to the `WEATHER_DATE` and `ZIP_CODE`. + +Extended high and low are for `WEATHER_DATE + 7`, so a week from the date. + +### Roles + +Object grants shall be given to roles, and the roles then assigned to users. Example: +```sql +CREATE ROLE myrole; +GRANT SELECT, INSERT, UPDATE ON example TO myrole; +CREATE USER me; +GRANT myrole TO me; +``` + +#### Role 0 : `librarian` + +- Grant `SELECT` on all `loc*` tables. + +#### Role 1: `weatherman` + +- Grant `INSERT` and `UPDATE` on all `loc_weather*` tables. + +#### Role 2: `reporter` + +- Grant `INSERT`, `UPDATE` on `loc`. + +#### Role 3: `garbageman` + +- Grant `DELETE` on all `loc*` tables. +- Grant ability to build statistics on all `loc*` tables. +- Depending on the DB used, may also need grants on keys and constraints in order to rebuild the stats on their indexes or other stat-holding objects. + +#### Role 4: `developer` + +- Grant `ALL` on the applicable schema. +- CANNOT access or alter `SYSTEM` type schemas, views, etc. + +### Users + +#### User 1: `dbuser` + +- Granted the `librarian` and `developer` role. +- Used by the main contributors of the project to test in stage environments. +- Used by the project owner(s) in production to apply patch scripts. + +#### User 2: `climate` + +- Granted the `librarian` and `weatherman` role. +- Used by a local process to add and aggregate weather data. + +#### User 3: `geo` + +- Granted the `librarian` and `reporter` role. +- Used by a local process to pull weather data and post new locations. + +#### User 4: `purge` + +- Granted the `librarian` and `garbageman` role. +- User / schema who owns the purge routines if they are intalled in the DB. +- Otherwise, this is the user who logs in and runs external purge scripts. + +#### As Needed: leetbro, hackersis, othercoolalias + +Contributors to this project may have their accounts created in test and stage +environments as necessary. Otherwise the contributors known as DB admins shall +handle all applicable DB support and modifications. + ## 3. Weather Fetcher ### Description ### Requirements +- Assume the database is local, just as would be during local devlopment. Will +not need to access via domain name or a special port, only localhost:defaut_port. +- Program shall use its own API key(s) to access the weather data. May use a +pool of keys if necessary to alleviate bandwidth or throttling. + +#### Aggregations + +For each `ZIP_CODE`, calculate the following: + +- Weekly Mean +- Weekly Median +- Weekly Mode + ## 4. Response API ### Description ### Requirements + +-