# rkt024/pam_final architecture

> Architecture diagram of the GitHub repository rkt024/pam_final, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rkt024/pam_final
- Repository: https://github.com/rkt024/pam_final

## Overview

1. **Overall shape**
   - This repository is a **single-process Streamlit application** that serves an internal office portal for DOLMA.
   - The architecture is split into a thin UI layer, a service layer for external API/database access, and a small utility layer for auth/session handling.

2. **Application entry point and routing**
   - `app.py` is the top-level Streamlit entry point.
   - It likely initializes global styles, session state, and page routing between the app’s main views.
   - `pages/` contains the actual screens, while `components/` provides reusable UI pieces.

3. **UI layer: pages**
   - `pages/login.py` handles authentication input and token acquisition.
   - `pages/dashboard.py` provides quick operational actions like Transfer and Return.
   - `pages/check_ref_status.py` is the detailed lookup view for a reference number, including status and timeline-style information.
   - The app is organized around staff workflows rather than public navigation.

4. **Reusable UI components**
   - `components/sidebar.py` likely owns navigation, theme controls, and logout behavior.
   - `components/table.py` encapsulates the tabular process views, including pagination/search/export/action buttons.
   - This keeps repeated UI patterns centralized across the different process pages.

5. **External system integration**
   - The app talks to the DOLMA backend through HTTP APIs.
   - `services/data_service.py` is the main integration boundary for operations like fetch, transfer, return, and verify.
   - The backend is exposed through a `/pam/api/...` surface, with authentication using bearer tokens.

6. **Authentication and token lifecycle**
   - Login is done with DOLMA credentials entered at runtime; credentials are not stored in the repo configuration.
   - `utils/api.py` wraps HTTP requests and automatically retries after a silent re-login when the token expires or the API returns 401/403.
   - The token is kept only in Streamlit session state, so auth is session-scoped rather than persisted.

7. **Session and app state**
   - `utils/state.py` appears to centralize Streamlit session initialization and flash-message style UI state.
   - This is important because Streamlit reruns the script frequently; shared session state is what keeps the user logged in and preserves workflow context.

8. **Local persistence**
   - `services/tracking_db_service.py` manages a local **SQLite** database used only for tracking user-marked verified references.
   - The table is keyed by `reference_no` and `checked_by`, so verification markers are isolated per user.
   - This is not the source of truth for DOLMA records; it is a local convenience/cache for UI badges and check marks.

9. **Configuration boundary**
   - `config.py` contains repo-level constants such as the base API URL, process IDs, and page mappings.
   - The README shows process IDs for different land-management workflows, which drive which tabs and data queries appear in the UI.
   - `.env` values control persistence paths and SSL verification, but operational credentials are always entered interactively.

10. **Data flow for common actions**
   - User signs in on the login page → Streamlit stores the token in session state.
   - The dashboard or table/detail views call service functions → services call DOLMA APIs through the wrapped HTTP layer.
   - Results are rendered in tables and detail panels; some actions mutate remote workflow state, and others only update the local SQLite tracking DB.

11. **Process-oriented table views**
   - The portal is centered on multiple land-record process types, including Rokka/Fukuwa and several other reference categories.
   - The tables page(s) likely reuse the same component but vary by process ID, filters, and available actions.
   - CSV export is a presentation-layer feature, not a backend service.

12. **Deployment and runtime**
   - The app runs as a **Streamlit server** on port 8501.
   - Docker and Docker Compose are first-class deployment paths, with persistent volume support for the SQLite tracking database.
   - The Docker setup matters architecturally because it separates ephemeral app runtime from durable local tracking data.

13. **Operational boundaries**
   - There are two distinct data domains: the remote DOLMA system of record, and the local SQLite tracking store.
   - The UI reads from and writes to both, but only the DOLMA API drives authoritative land-record state.
   - SSL verification is configurable because the app may run in environments with different certificate trust requirements.

14. **What to show in an architecture diagram**
   - A good diagram should include: browser/user → Streamlit app (`app.py`) → page components → service layer → external DOLMA API, plus a separate path from the UI/service layer to local SQLite tracking storage.
   - Also show session state/token management as an app-internal cross-cutting concern, not a separate service.

Main entry points: [`app.py`](https://github.com/rkt024/pam_final/blob/main/app.py) (Streamlit app), [`services/data_service.py`](https://github.com/rkt024/pam_final/blob/main/services/data_service.py) (Data service), [`pages/login.py`](https://github.com/rkt024/pam_final/blob/main/pages/login.py) (Login), [`pages/dashboard.py`](https://github.com/rkt024/pam_final/blob/main/pages/dashboard.py) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI layer"]
  node_app["Streamlit app<br/>entrypoint<br/>[app.py]"]
  node_login_page["Login<br/>page<br/>[login.py]"]
  node_dashboard_page["Dashboard<br/>page<br/>[dashboard.py]"]
  node_check_page["Ref status<br/>page"]
  node_sidebar["Sidebar<br/>ui component<br/>[sidebar.py]"]
  node_table["Tables<br/>ui component<br/>[table.py]"]
end

subgraph group_core["Core services"]
  node_state[("Session state<br/>state util<br/>[state.py]")]
  node_api["HTTP client<br/>api util<br/>[api.py]"]
  node_data_service["Data service<br/>[data_service.py]"]
  node_config["Config<br/>settings<br/>[config.py]"]
end

subgraph group_storage["Storage"]
  node_tracking_service[("Tracking DB")]
  node_dolma_api{{"DOLMA API<br/>external system"}}
  node_sqlite_db[("SQLite store<br/>local storage")]
end

subgraph group_deploy["Deployment"]
  node_docker["Docker runtime<br/>deployment"]
  node_compose["Compose setup<br/>deployment<br/>[docker-compose.yml]"]
end

node_user(("User<br/>actor"))

node_user -->|"opens"| node_app
node_app -->|"initializes"| node_state
node_app -->|"renders"| node_sidebar
node_app -->|"routes to"| node_login_page
node_app -->|"routes to"| node_dashboard_page
node_app -->|"routes to"| node_check_page
node_dashboard_page -->|"uses"| node_table
node_check_page -->|"uses"| node_table
node_sidebar -->|"reads"| node_state
node_login_page -->|"authenticates via"| node_api
node_login_page -->|"stores token"| node_state
node_dashboard_page -->|"calls"| node_data_service
node_check_page -->|"calls"| node_data_service
node_table -->|"loads data"| node_data_service
node_data_service -->|"requests through"| node_api
node_api -->|"talks to"| node_dolma_api
node_data_service -->|"updates"| node_tracking_service
node_tracking_service -->|"persists to"| node_sqlite_db
node_app -->|"reads"| node_config
node_data_service -->|"uses"| node_config
node_docker -->|"runs"| node_app
node_compose -->|"orchestrates"| node_docker
node_compose -->|"mounts"| node_sqlite_db

click node_app "https://github.com/rkt024/pam_final/blob/main/app.py"
click node_login_page "https://github.com/rkt024/pam_final/blob/main/pages/login.py"
click node_dashboard_page "https://github.com/rkt024/pam_final/blob/main/pages/dashboard.py"
click node_check_page "https://github.com/rkt024/pam_final/blob/main/pages/check_ref_status.py"
click node_sidebar "https://github.com/rkt024/pam_final/blob/main/components/sidebar.py"
click node_table "https://github.com/rkt024/pam_final/blob/main/components/table.py"
click node_state "https://github.com/rkt024/pam_final/blob/main/utils/state.py"
click node_api "https://github.com/rkt024/pam_final/blob/main/utils/api.py"
click node_data_service "https://github.com/rkt024/pam_final/blob/main/services/data_service.py"
click node_tracking_service "https://github.com/rkt024/pam_final/blob/main/services/tracking_db_service.py"
click node_config "https://github.com/rkt024/pam_final/blob/main/config.py"
click node_docker "https://github.com/rkt024/pam_final/tree/main/Dockerfile"
click node_compose "https://github.com/rkt024/pam_final/blob/main/docker-compose.yml"

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_app,node_login_page,node_dashboard_page,node_check_page,node_sidebar,node_table toneBlue
class node_state,node_api,node_data_service,node_config toneAmber
class node_tracking_service,node_dolma_api,node_sqlite_db toneMint
class node_docker,node_compose toneRose
class node_user toneNeutral
```

## Components

### UI layer

Streamlit entrypoint, pages, and reusable components

- [Streamlit app](https://github.com/rkt024/pam_final/blob/main/app.py): entrypoint · Top-level app bootstrap and routing · `app.py`
- [Login](https://github.com/rkt024/pam_final/blob/main/pages/login.py): page · Credential entry and token acquisition · `pages/login.py`
- [Dashboard](https://github.com/rkt024/pam_final/blob/main/pages/dashboard.py): page · Operational actions and quick workflow entry · `pages/dashboard.py`
- [Ref status](https://github.com/rkt024/pam_final/blob/main/pages/check_ref_status.py): page · Reference lookup and timeline view · `pages/check_ref_status.py`
- [Sidebar](https://github.com/rkt024/pam_final/blob/main/components/sidebar.py): ui component · Navigation and session actions · `components/sidebar.py`
- [Tables](https://github.com/rkt024/pam_final/blob/main/components/table.py): ui component · Shared tabular workflow presentation · `components/table.py`

### Core services

API access, session state, and app configuration

- [Session state](https://github.com/rkt024/pam_final/blob/main/utils/state.py): state util · Streamlit session initialization and flash state · `utils/state.py`
- [HTTP client](https://github.com/rkt024/pam_final/blob/main/utils/api.py): api util · Wrapped API calls with token handling and retry · `utils/api.py`
- [Data service](https://github.com/rkt024/pam_final/blob/main/services/data_service.py): service · Main DOLMA workflow integration boundary · `services/data_service.py`
- [Config](https://github.com/rkt024/pam_final/blob/main/config.py): settings · API base URL, process IDs, and page mappings · `config.py`

### Storage

Local tracking database and external system of record

- [Tracking DB](https://github.com/rkt024/pam_final/blob/main/services/tracking_db_service.py): service · Local verification tracking on SQLite · `services/tracking_db_service.py`
- **DOLMA API**: external system · Remote authoritative land-record backend
- **SQLite store**: local storage · Persistent local tracking database

### Deployment

Containerized runtime and environment setup

- [Docker runtime](https://github.com/rkt024/pam_final/tree/main/Dockerfile): deployment · Containerized Streamlit deployment · `Dockerfile`
- [Compose setup](https://github.com/rkt024/pam_final/blob/main/docker-compose.yml): deployment · Multi-container and volume orchestration · `docker-compose.yml`

### Other components

- **User**: actor · Staff member using the portal

## Connections

- User → Streamlit app: opens · User starts the Streamlit application
- Streamlit app → Session state: initializes · Session state is prepared during app startup
- Streamlit app → Sidebar: renders · Global navigation and session actions are mounted
- Streamlit app → Login: routes to · Login screen is one of the main pages
- Streamlit app → Dashboard: routes to · Dashboard screen is one of the main pages
- Streamlit app → Ref status: routes to · Reference status screen is one of the main pages
- Dashboard → Tables: uses · Dashboard reuses shared table patterns for workflows
- Ref status → Tables: uses · Reference lookup view relies on the shared table component
- Sidebar → Session state: reads · Sidebar reacts to session/login state
- Login → HTTP client: authenticates via · Login obtains bearer tokens through the HTTP layer
- Login → Session state: stores token · Token is kept in Streamlit session state
- Dashboard → Data service: calls · Operational actions are executed through the service layer
- Ref status → Data service: calls · Reference lookup and history queries use services
- Tables → Data service: loads data · Table views pull workflow records via service functions
- Data service → HTTP client: requests through · Service boundary delegates HTTP work to the API wrapper
- HTTP client → DOLMA API: talks to · Remote DOLMA backend is the system of record
- Data service → Tracking DB: updates · Verification markers are written to the local tracker
- Tracking DB → SQLite store: persists to · SQLite holds per-user checked references
- Streamlit app → Config: reads · Top-level settings and page mappings are configured centrally
- Data service → Config: uses · Process IDs and API endpoints drive workflow behavior
- Docker runtime → Streamlit app: runs · Container image launches the Streamlit app
- Compose setup → Docker runtime: orchestrates · Compose defines the runtime and volume setup
- Compose setup → SQLite store: mounts · Persistent volume keeps local tracking data durable