LafaekStreet — User Roles & Access Levels

Two Separate Tables, Two Separate Systems

LafaekStreet uses two different tables for authentication depending on the application:

Table	App	Login Method	Purpose
users	Mobile App (Flutter) + Admin Panel (:3002)	App: Email/Google OAuth; Admin: Email + Password + TOTP 2FA	Citizens report issues, admins manage system
government_agencies	Gov Portal (Next.js :3001)	Email + Password + Email 2FA	Agencies manage & resolve reports

---

users Table Roles

These roles exist in the users table (user_role enum):

citizen

• Who: Regular Timor-Leste residents
• How they register: Self-registration via mobile app (email or Google)
• What they do:
  • Submit infrastructure reports (potholes, broken lights, drainage, etc.)
  • Upload photos of issues
  • Track their own report status
  • Receive notifications on updates
  • View public dashboard
• Access: Mobile app + Public dashboard only
• Cannot: Access Gov Portal or Admin Panel
• Login: Mobile app → email/password or Google OAuth

admin

• Who: LafaekStreet internal system administrators (not government staff)
• How they're created: First admin via /setup page (requires ADMIN_SETUP_TOKEN), additional admins created via Admin Panel
• This is NOT a government role. This is the LafaekStreet platform team — the developers/operators who built and maintain the system.
• What they do:
  • Create and manage government agency accounts (in government_agencies table)
  • Create other admin/moderator/gov_official user accounts
  • Configure app settings (app_settings table)
  • Moderate all reports across all agencies
  • Manage the full system lifecycle
  • View all analytics, logs, and audit trails
• Access: Admin Panel (lafaekstreet_admin :3002)
• Think of them as: The "IT department" running LafaekStreet

government_official

• Who: Individual government staff members who need a personal user account
• How they're created: By an admin via Admin Panel (lafaekstreet_admin :3002)
• Why this exists alongside government_agencies:
  • government_agencies = organization-level account (e.g., "DNSSA" as a whole)
  • government_official in users = individual person account (e.g., "João Silva who works at DNSSA")
  • Sometimes you need to track WHO within an agency did something, not just WHICH agency
• What they do:
  • View reports related to their area
  • Add comments/updates on reports
  • Limited admin panel access
• Access: Admin Panel (limited views)
• Current status: The Gov Portal shows them in the Users list but they cannot log in to the Gov Portal — only government_agencies accounts can log in there

moderator

• Who: Trusted community members or LafaekStreet staff who help review content
• How they're created: Promoted by admin
• What they do:
  • Review and flag inappropriate reports
  • Moderate citizen comments
  • Help triage and categorize incoming reports
  • Verify report accuracy
• Access: Admin Panel (moderation views only)
• Cannot: Log in to Gov Portal

---

government_agencies Table — Government Portal Login

The government_agencies table is completely separate from users. Each row = one organization account.

Agency Types (agency_type enum)

Type	Example	Scope
municipal	Dili Municipal Infrastructure Dept	One municipality
national	DNSSA (National Sanitation)	All municipalities
contractor	Private repair company	Assigned jobs only
utility	EDTL (Electricity of Timor-Leste)	Utility infrastructure
other	NGOs, special agencies	Varies

What Agency Accounts Can Do (Gov Portal)

• Log in with email + password + 2FA (6-digit email code)
• View dashboard with statistics
• Browse, filter, and search all reports
• Update report status (pending → under_review → in_progress → fixed)
• Assign reports to other agencies
• Add official comments to reports
• View analytics (municipality breakdown, agency performance)
• View map with all report locations
• View blockchain verification (Hedera HCS)
• Export data as CSV
• Change their own password
• View all agencies and users

Agency Login Flow (Gov Portal :3001)

1. Agency enters email + password → /login
2. System verifies against government_agencies table (bcrypt)
3. System sends 6-digit code to agency email
4. Agency enters code → /verify-2fa
5. JWT session cookie set (gov_session, 24h)
6. Max 3 2FA attempts per day, then locked until tomorrow

Admin Login Flow (Admin Panel :3002)

1. Admin enters email + password → /login
2. System verifies against users table where role = 'admin' (bcrypt)
3. If TOTP 2FA enabled → redirect to /2fa for authenticator app code
4. If TOTP 2FA not enabled → login directly
5. JWT session cookie set (admin_session, 24h)

First-Time Admin Setup

1. Visit /setup on Admin Panel
2. Enter ADMIN_SETUP_TOKEN (set in .env)
3. Enter email + password for first admin account
4. System creates user with role = 'admin' in users table
5. Only works if no admin user exists yet

---

User Management — Separated by Application

The Gov Portal does NOT manage users table accounts (admin, government_official, moderator). That responsibility belongs to the Admin Panel (lafaekstreet_admin on port 3002).

What each app manages:

App	Manages	Table
Gov Portal (lafaekstreet_govportal :3001)	Agency accounts	government_agencies
Admin Panel (lafaekstreet_admin :3002)	Admin, gov_official, moderator, citizen accounts	users
Mobile App (lafaekstreet_app)	Citizen self-registration	users

Gov Portal can only:

• Create/manage agency accounts (in government_agencies table)
• View agency list and details
• Agencies manage their own profile and password

Admin Panel handles:

• Create/manage admin accounts
• Create/manage government_official accounts
• Create/manage moderator accounts
• Content moderation (comments, images)
• System configuration and settings
• Analytics and blockchain verification
• Database tools and SQL console
• Security audit logs and session management
• Data export (CSV, Excel, PDF)
• Full system oversight

---

Complete Access Matrix

Action	citizen	admin	gov_official	moderator	agency (Gov Portal)
Submit reports	Yes	—	—	—	—
View own reports	Yes	—	—	—	—
View all reports	—	Yes	Limited	Yes	Yes
Update report status	—	Yes	—	—	Yes
Assign to agency	—	Yes	—	—	Yes
Add official comment	—	Yes	Yes	—	Yes
Create users	—	Yes (Admin Panel)	—	—	—
Create agencies	—	Yes	—	—	Yes
View analytics	—	Yes	Limited	—	Yes
View map	—	Yes	—	—	Yes
Export CSV	—	Yes	—	—	Yes
Moderate content	—	Yes	—	Yes	—
Configure settings	—	Yes	—	—	Read-only
Change password	—	Yes (Admin Panel)	—	—	Yes
SQL console	—	Yes	—	—	—
2FA setup (TOTP)	—	Yes	—	—	—
Login method	App (OAuth)	Admin Panel (TOTP 2FA)	Admin Panel	Admin Panel	Gov Portal (Email 2FA)
Table	users	users	users	users	government_agencies

---

Database Reference

-- Users table roles (for mobile app + admin panel)
CREATE TYPE user_role AS ENUM ('citizen', 'admin', 'government_official', 'moderator');

-- Agency types (for government portal)
CREATE TYPE agency_type AS ENUM ('municipal', 'national', 'contractor', 'utility', 'other');

Full schema: Database/schema.sql