{"id":44319411,"url":"https://github.com/pitabwire/thesa-ui","last_synced_at":"2026-02-11T06:07:23.002Z","repository":{"id":336860572,"uuid":"1151354875","full_name":"pitabwire/thesa-ui","owner":"pitabwire","description":null,"archived":false,"fork":false,"pushed_at":"2026-02-06T19:38:37.000Z","size":157,"stargazers_count":0,"open_issues_count":30,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-06T21:10:45.202Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pitabwire.png","metadata":{"files":{"readme":"docs/README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-06T11:09:06.000Z","updated_at":"2026-02-06T19:38:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pitabwire/thesa-ui","commit_stats":null,"previous_names":["pitabwire/thesa-ui"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/pitabwire/thesa-ui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitabwire%2Fthesa-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitabwire%2Fthesa-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitabwire%2Fthesa-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitabwire%2Fthesa-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pitabwire","download_url":"https://codeload.github.com/pitabwire/thesa-ui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitabwire%2Fthesa-ui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29327985,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T03:52:29.695Z","status":"ssl_error","status_checked_at":"2026-02-11T03:52:23.094Z","response_time":97,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-11T06:07:22.224Z","updated_at":"2026-02-11T06:07:22.995Z","avatar_url":"https://github.com/pitabwire.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Thesa UI — Architecture Documentation\n\n## Enterprise Capability-Driven UI Runtime for Flutter\n\nThesa UI is a generic, dynamic frontend that renders enterprise admin interfaces entirely from backend (BFF) descriptors. It contains zero hardcoded domain knowledge. Every screen, form, table, action, and workflow is built at runtime from server-provided contracts.\n\n---\n\n## Documentation Index\n\n### Foundations\n\n| # | Section | Description | Audience |\n|---|---|---|---|\n| 01 | [Executive Summary](./01-executive-summary.md) | What Thesa UI is, why it exists, and its core principles | Everyone |\n| 02 | [Technology Choices](./02-technology-choices.md) | Every library used, why it was chosen, and how it fits | Developers, Architects |\n| 03 | [Layered Architecture](./03-layered-architecture.md) | The six layers, their responsibilities, and communication rules | Developers, Architects |\n| 04 | [Folder Structure](./04-folder-structure.md) | Every folder and file explained with navigation rules | Developers |\n\n### Data \u0026 State\n\n| # | Section | Description | Audience |\n|---|---|---|---|\n| 05 | [Offline-First Cache](./05-offline-first-cache.md) | Database schema, cache lifecycle, TTL, ETags, stale-while-revalidate | Developers, Architects |\n| 06 | [State Architecture](./06-state-architecture.md) | Riverpod providers, dependency tree, cache-first pattern, permissions | Developers |\n\n### Dynamic UI\n\n| # | Section | Description | Audience |\n|---|---|---|---|\n| 07 | [Dynamic UI Engine](./07-dynamic-ui-engine.md) | Page rendering pipeline, component registry, BFF response examples | Developers |\n| 08 | [Dynamic Form Engine](./08-dynamic-form-engine.md) | Schema-to-form pipeline, all field types, validation, conditional fields | Developers |\n| 09 | [Dynamic Table Engine](./09-dynamic-table-engine.md) | Pagination, sorting, filtering, column priority, bulk actions, virtualization | Developers |\n| 10 | [Workflow Engine](./10-workflow-engine.md) | State machine, step rendering, branching, persistence, polling | Developers |\n\n### Navigation \u0026 Layout\n\n| # | Section | Description | Audience |\n|---|---|---|---|\n| 11 | [Dynamic Navigation](./11-dynamic-navigation.md) | Route generation, sidebar, breadcrumbs, deep linking, route guards | Developers |\n| 12 | [Responsive Layout](./12-responsive-layout.md) | Breakpoints, shell adaptation, content layout rules per screen size | Developers, Designers |\n\n### Extensibility\n\n| # | Section | Description | Audience |\n|---|---|---|---|\n| 13 | [Plugin System](./13-plugin-system.md) | Page, component, and schema plugins; resolution order; packaging | Developers, Domain Teams |\n\n### Operations\n\n| # | Section | Description | Audience |\n|---|---|---|---|\n| 14 | [Authentication \u0026 Session](./14-authentication-session.md) | Token flow, refresh, logout, session management, login screen | Developers, Security |\n| 15 | [Error Handling](./15-error-handling.md) | Error categories, UX treatment, ErrorBoundary, graceful degradation | Developers, QA |\n| 16 | [Telemetry \u0026 Observability](./16-telemetry-observability.md) | Instrumented events, OpenTelemetry export, key metrics | Developers, Ops |\n\n### Quality \u0026 Performance\n\n| # | Section | Description | Audience |\n|---|---|---|---|\n| 17 | [Performance Strategy](./17-performance.md) | Virtualization, debouncing, rebuild optimization, performance budgets | Developers |\n| 18 | [Testing Strategy](./18-testing-strategy.md) | Unit, widget, golden tests; what to test; test organization; CI | Developers, QA |\n| 19 | [Security Principles](./19-security.md) | No local permissions, absent (not disabled) elements, token security | Everyone |\n\n### System Overview\n\n| # | Section | Description | Audience |\n|---|---|---|---|\n| 20 | [Data Flow \u0026 Scalability](./20-data-flow-startup-scalability.md) | Complete data flow, startup sequences, scalability axes | Developers, Architects |\n| 21 | [Networking Layer](./21-networking-layer.md) | BFF endpoints, interceptor chain, retries, cancellation, background refresh | Developers |\n| 22 | [Design System](./22-design-system.md) | Color tokens, typography, spacing, dark mode, branding, accessibility | Developers, Designers |\n| 23 | [Architectural Decisions](./23-architectural-decisions.md) | ADRs for all major technology and design decisions | Architects, Tech Leads |\n\n---\n\n## Reading Order\n\n### If you are new to the project\n\nRead in order: 01 → 02 → 03 → 04. This gives you the full context.\nThen read the sections relevant to your work.\n\n### If you are a frontend developer\n\nStart with: 01, 03, 04, 06, 07. Then read whichever component you are working on (forms: 08, tables: 09, workflows: 10).\n\n### If you are a backend / BFF developer\n\nStart with: 01, 07, 08, 09, 10, 11. These sections show the exact JSON contracts the frontend expects.\n\n### If you are a designer\n\nStart with: 01, 12, 22. These cover the responsive strategy and design system.\n\n### If you are a domain team building plugins\n\nStart with: 01, 07, 13. Section 13 is the plugin guide.\n\n### If you are reviewing security\n\nStart with: 14, 19, 05 (cache security section).\n\n### If you are an architect evaluating the system\n\nStart with: 01, 03, 23 (ADRs), 20, 05.\n\n---\n\n## Key Concepts Quick Reference\n\n| Concept | Meaning | Detailed In |\n|---|---|---|\n| **BFF** | Backend-For-Frontend — the single server the UI talks to | Section 01 |\n| **Capability-driven** | UI only shows what the server declares available | Section 01 |\n| **Schema-driven** | Forms and tables built from data structure definitions | Section 08, 09 |\n| **Offline-first** | Always render from cache; refresh in background | Section 05 |\n| **Stale-while-revalidate** | Return cached data immediately, even if stale; refresh behind the scenes | Section 05 |\n| **Family provider** | A Riverpod provider that creates separate instances per parameter | Section 06 |\n| **Component Registry** | Lookup table mapping BFF component types to Flutter widgets | Section 07 |\n| **Plugin Registry** | Registry for custom overrides of pages, components, or schema renderers | Section 13 |\n| **ErrorBoundary** | Widget wrapper that catches rendering errors, preventing page-wide crashes | Section 15 |\n| **Design tokens** | Named values (colors, fonts, spacing) ensuring visual consistency | Section 22 |\n| **ADR** | Architectural Decision Record — documents why a decision was made | Section 23 |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpitabwire%2Fthesa-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpitabwire%2Fthesa-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpitabwire%2Fthesa-ui/lists"}