rkt024/pam_final

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.