# rnrinfodgl18/talco_members_portal architecture

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

- Interactive diagram: https://gitdiagram.com/rnrinfodgl18/talco_members_portal
- Repository: https://github.com/rnrinfodgl18/talco_members_portal

## Overview

TALCO CETP Member Portal combines a role-based member/staff web portal with an API for accounts, ledgers, circulars, administration and financial-data imports. The main user flow is sign-in, navigate a role-appropriate page, and view or manage portal data; administrators also import voucher files for parsing, matching and posting. The graph preserves the documented portal areas and the visible import-processing layers. Router-to-service wiring and several page-to-endpoint links are not shown in the excerpts, so those connections are omitted rather than inferred.

Main entry points: [`api/app/main.py`](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/main.py) (API application), [`web/src/App.tsx`](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/web/src/App.tsx) (Portal shell), [`api/app/services/import_pipeline.py`](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/services/import_pipeline.py) (Import posting), [`api/app/security.py`](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/security.py) (Token security)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web portal"]
  node_webapp["Portal shell<br/>[App.tsx]"]
  node_authpage["Sign-in<br/>[AuthPage.tsx]"]
  node_portalpage["Member portal<br/>[PortalPage.tsx]"]
  node_adminpages["Admin pages"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and access"]
  node_api_entry["API application<br/>[main.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_access_routes["User access<br/>[user_access.py]"]
  node_portal_routes["Portal routes<br/>[portal.py]"]
  node_settings_routes["Settings routes<br/>[settings.py]"]
  node_business_routes["Business routes"]
  node_security["Token security<br/>[security.py]"]
  node_import_routes["Import routes<br/>[imports.py]"]
  node_mapping_routes["Mapping routes<br/>[mappings.py]"]
end

subgraph group_import["Import processing"]
  node_import_pipeline["Import posting<br/>[import_pipeline.py]"]
  node_voucher_parser["Voucher parsing<br/>[parser.py]"]
  node_excel_parser["Excel parsing<br/>[excel_parser.py]"]
  node_matching["Party matching<br/>[matcher.py]"]
  node_normalization["Name normalization<br/>[normalize.py]"]
  node_master_load["Master loading<br/>[master_load.py]"]
end

subgraph group_domain["Domain and persistence"]
  node_entity_models["Business records<br/>[entities.py]"]
  node_auth_models["Account records<br/>[auth.py]"]
  node_database[("SQL database<br/>[db.py]")]
end

node_member(("Portal user"))

node_member -->|"uses"| node_webapp
node_webapp -->|"shows"| node_authpage
node_webapp -->|"routes to"| node_portalpage
node_webapp -->|"routes to"| node_adminpages
node_webapp -->|"fetches auth and settings"| node_api_entry
node_api_entry -->|"registers"| node_auth_routes
node_api_entry -->|"registers"| node_access_routes
node_api_entry -->|"registers"| node_portal_routes
node_api_entry -->|"registers"| node_settings_routes
node_api_entry -->|"registers"| node_business_routes
node_api_entry -->|"registers"| node_import_routes
node_api_entry -->|"registers"| node_mapping_routes
node_api_entry -->|"opens sessions"| node_database
node_auth_routes -->|"uses token helpers"| node_security
node_auth_routes -->|"reads and writes"| node_auth_models
node_security -->|"checks tokens and users"| node_auth_models
node_portal_routes -->|"queries portal data"| node_entity_models
node_portal_routes -->|"requires authentication"| node_security
node_settings_routes -->|"requires authentication"| node_security
node_settings_routes -->|"uses models"| node_entity_models
node_import_pipeline -->|"uses parser"| node_voucher_parser
node_import_pipeline -->|"uses matching"| node_matching
node_import_pipeline -->|"uses normalization"| node_normalization
node_import_pipeline -->|"creates and updates records"| node_entity_models
node_voucher_parser -->|"dispatches spreadsheets"| node_excel_parser
node_matching -->|"normalizes names"| node_normalization
node_master_load -->|"uses matching"| node_matching
node_master_load -->|"uses normalization"| node_normalization
node_webapp -->|"imports client"| node_api_client

click node_webapp "https://github.com/rnrinfodgl18/talco_members_portal/blob/main/web/src/App.tsx"
click node_authpage "https://github.com/rnrinfodgl18/talco_members_portal/blob/main/web/src/AuthPage.tsx"
click node_portalpage "https://github.com/rnrinfodgl18/talco_members_portal/blob/main/web/src/PortalPage.tsx"
click node_adminpages "https://github.com/rnrinfodgl18/talco_members_portal/tree/main/web/src"
click node_api_client "https://github.com/rnrinfodgl18/talco_members_portal/blob/main/web/src/api.ts"
click node_api_entry "https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/main.py"
click node_auth_routes "https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/routers/auth.py"
click node_access_routes "https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/routers/user_access.py"
click node_portal_routes "https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/routers/portal.py"
click node_settings_routes "https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/routers/settings.py"
click node_business_routes "https://github.com/rnrinfodgl18/talco_members_portal/tree/main/api/app/routers"
click node_security "https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/security.py"
click node_import_routes "https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/routers/imports.py"
click node_mapping_routes "https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/routers/mappings.py"
click node_import_pipeline "https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/services/import_pipeline.py"
click node_voucher_parser "https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/importer/parser.py"
click node_excel_parser "https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/importer/excel_parser.py"
click node_matching "https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/importer/matcher.py"
click node_normalization "https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/importer/normalize.py"
click node_master_load "https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/services/master_load.py"
click node_entity_models "https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/models/entities.py"
click node_auth_models "https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/models/auth.py"
click node_database "https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/db.py"

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_webapp,node_authpage,node_portalpage,node_adminpages,node_api_client,node_member toneBlue
class node_api_entry,node_auth_routes,node_access_routes,node_portal_routes,node_settings_routes,node_business_routes,node_security,node_import_routes,node_mapping_routes toneAmber
class node_import_pipeline,node_voucher_parser,node_excel_parser,node_matching,node_normalization,node_master_load toneMint
class node_entity_models,node_auth_models,node_database toneRose
```

## Components

### Web portal

- [Portal shell](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Sign-in](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/web/src/AuthPage.tsx): `web/src/AuthPage.tsx`
- [Member portal](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/web/src/PortalPage.tsx): `web/src/PortalPage.tsx`
- [Admin pages](https://github.com/rnrinfodgl18/talco_members_portal/tree/main/web/src): `web/src`
- [API client](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/web/src/api.ts): `web/src/api.ts`

### API and access

- [API application](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/main.py): `api/app/main.py`
- [Authentication routes](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/routers/auth.py): `api/app/routers/auth.py`
- [User access](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/routers/user_access.py): `api/app/routers/user_access.py`
- [Portal routes](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/routers/portal.py): `api/app/routers/portal.py`
- [Settings routes](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/routers/settings.py): `api/app/routers/settings.py`
- [Business routes](https://github.com/rnrinfodgl18/talco_members_portal/tree/main/api/app/routers): `api/app/routers`
- [Token security](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/security.py): `api/app/security.py`
- [Import routes](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/routers/imports.py): `api/app/routers/imports.py`
- [Mapping routes](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/routers/mappings.py): `api/app/routers/mappings.py`

### Import processing

- [Import posting](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/services/import_pipeline.py): `api/app/services/import_pipeline.py`
- [Voucher parsing](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/importer/parser.py): `api/app/importer/parser.py`
- [Excel parsing](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/importer/excel_parser.py): `api/app/importer/excel_parser.py`
- [Party matching](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/importer/matcher.py): `api/app/importer/matcher.py`
- [Name normalization](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/importer/normalize.py): `api/app/importer/normalize.py`
- [Master loading](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/services/master_load.py): `api/app/services/master_load.py`

### Domain and persistence

- [Business records](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/models/entities.py): `api/app/models/entities.py`
- [Account records](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/models/auth.py): `api/app/models/auth.py`
- [SQL database](https://github.com/rnrinfodgl18/talco_members_portal/blob/main/api/app/db.py): `api/app/db.py`

### Other components

- **Portal user**

## Connections

- Portal user → Portal shell: uses (evidence: `web/src/App.tsx`)
- Portal shell → Sign-in: shows (evidence: `web/src/App.tsx`)
- Portal shell → Member portal: routes to (evidence: `web/src/App.tsx`)
- Portal shell → Admin pages: routes to (evidence: `web/src/App.tsx`)
- Portal shell → API application: fetches auth and settings (evidence: `web/src/App.tsx`)
- API application → Authentication routes: registers (evidence: `api/app/main.py`)
- API application → User access: registers (evidence: `api/app/main.py`)
- API application → Portal routes: registers (evidence: `api/app/main.py`)
- API application → Settings routes: registers (evidence: `api/app/main.py`)
- API application → Business routes: registers (evidence: `api/app/main.py`)
- API application → Import routes: registers (evidence: `api/app/main.py`)
- API application → Mapping routes: registers (evidence: `api/app/main.py`)
- API application → SQL database: opens sessions (evidence: `api/app/main.py`)
- Authentication routes → Token security: uses token helpers (evidence: `api/app/routers/auth.py`)
- Authentication routes → Account records: reads and writes (evidence: `api/app/routers/auth.py`)
- Token security → Account records: checks tokens and users (evidence: `api/app/security.py`)
- Portal routes → Business records: queries portal data (evidence: `api/app/routers/portal.py`)
- Portal routes → Token security: requires authentication (evidence: `api/app/routers/portal.py`)
- Settings routes → Token security: requires authentication (evidence: `api/app/routers/settings.py`)
- Settings routes → Business records: uses models (evidence: `api/app/routers/settings.py`)
- Import posting → Voucher parsing: uses parser (evidence: `api/app/services/import_pipeline.py`)
- Import posting → Party matching: uses matching (evidence: `api/app/services/import_pipeline.py`)
- Import posting → Name normalization: uses normalization (evidence: `api/app/services/import_pipeline.py`)
- Import posting → Business records: creates and updates records (evidence: `api/app/services/import_pipeline.py`)
- Voucher parsing → Excel parsing: dispatches spreadsheets (evidence: `api/app/importer/parser.py`)
- Party matching → Name normalization: normalizes names (evidence: `api/app/importer/matcher.py`)
- Master loading → Party matching: uses matching (evidence: `api/app/services/master_load.py`)
- Master loading → Name normalization: uses normalization (evidence: `api/app/services/master_load.py`)
- Portal shell → API client: imports client (evidence: `web/src/App.tsx`)
