# yecos/archii architecture

> Architecture diagram of the GitHub repository yecos/archii, 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/yecos/archii
- Repository: https://github.com/yecos/archii

## Overview

Archii is a multi-tenant construction project-management platform. Its main user journey runs from signing in and choosing a workspace, through project and field-work screens, to persistent records, dashboards, and reports. The README also describes AI-assisted work, collaboration, integrations, compliance, notifications, offline/PWA support, and a public API/SDK, so these appear as distinct branches. Relationships are limited to README statements and source-index references; unsampled implementation details are not assumed.

Main entry points: [`src/app/HomeContent.tsx`](https://github.com/yecos/archii/blob/main/src/app/HomeContent.tsx) (App shell), [`src/contexts/AppContext.tsx`](https://github.com/yecos/archii/blob/main/src/contexts/AppContext.tsx) (Application state), [`src/components/layout/AuthScreen.tsx`](https://github.com/yecos/archii/blob/main/src/components/layout/AuthScreen.tsx) (Sign-in), [`src/screens/DashboardScreen.tsx`](https://github.com/yecos/archii/blob/main/src/screens/DashboardScreen.tsx) (Dashboard and reports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["App experience"]
  node_auth["Sign-in<br/>[AuthScreen.tsx]"]
  node_workspace["Workspace selection"]
  node_app_shell["App shell<br/>[HomeContent.tsx]"]
  node_dashboard["Dashboard and reports"]
end

subgraph group_project_work["Project work"]
  node_project_screens["Project screens"]
  node_task_screen["Tasks and Kanban<br/>[TasksScreen.tsx]"]
  node_field_screens["Field operations"]
  node_inventory["Inventory<br/>[useInventory.tsx]"]
  node_time_tracking["Time tracking"]
end

subgraph group_platform["Platform services"]
  node_app_context["Application state<br/>[AppContext.tsx]"]
  node_firestore_actions["Entity operations"]
  node_firebase_client["Firebase client"]
  node_firebase_admin["Firebase Admin<br/>[firebase-admin.ts]"]
  node_api_auth["API authentication<br/>[api-auth.ts]"]
  node_api_routes["API routes"]
  node_ai["AI assistant and RAG"]
  node_compliance["Compliance and GDPR<br/>[route.ts]"]
end

subgraph group_connectivity["Integrations"]
  node_integrations["External integrations"]
  node_onedrive["OneDrive files"]
  node_messaging["Notifications and WhatsApp"]
  node_offline["PWA and offline<br/>[sw.js]"]
end

subgraph group_developer["Public API and SDK"]
  node_sdk_client["Archii SDK<br/>[client.ts]"]
  node_sdk_webhooks["Webhook SDK<br/>[webhooks.ts]"]
end

node_user(("User"))
node_firestore[("Firebase Firestore")]
node_firebase_auth["Firebase Auth"]
node_third_party["Third-party services"]

node_user -->|"signs in"| node_auth
node_auth -->|"selects workspace"| node_workspace
node_workspace -->|"opens app"| node_app_shell
node_app_shell -->|"shows screens"| node_dashboard
node_app_shell -->|"shows screens"| node_project_screens
node_app_shell -->|"shows screens"| node_task_screen
node_app_shell -->|"shows screens"| node_field_screens
node_app_shell -->|"uses state"| node_app_context
node_app_context -->|"calls"| node_firebase_client
node_app_context -->|"calls"| node_firestore_actions
node_firebase_client -->|"reads and writes"| node_firestore
node_auth -->|"authenticates with"| node_firebase_auth
node_dashboard -->|"summarizes"| node_time_tracking
node_dashboard -->|"summarizes"| node_inventory
node_task_screen -->|"uses tracking"| node_time_tracking
node_inventory -->|"reads context"| node_app_context
node_time_tracking -->|"reads context"| node_app_context
node_api_routes -->|"authenticates requests"| node_api_auth
node_api_auth -->|"verifies tokens"| node_firebase_admin
node_firebase_admin -->|"accesses"| node_firestore
node_api_routes -->|"includes"| node_compliance
node_compliance -->|"authenticates requests"| node_api_auth
node_compliance -.->|"handles GDPR data"| node_third_party
node_app_shell -->|"offers AI assistant"| node_ai
node_ai -->|"uses Gemini"| node_third_party
node_app_shell -->|"offers connectors"| node_integrations
node_app_shell -->|"browses files"| node_onedrive
node_app_shell -->|"shows notifications"| node_messaging
node_messaging -->|"sends messages"| node_third_party
node_app_shell -->|"supports offline"| node_offline
node_sdk_client -.->|"calls API"| node_api_routes
node_sdk_webhooks -->|"handles webhooks"| node_third_party

click node_auth "https://github.com/yecos/archii/blob/main/src/components/layout/AuthScreen.tsx"
click node_workspace "https://github.com/yecos/archii/blob/main/src/components/layout/TenantSelectionScreen.tsx"
click node_app_shell "https://github.com/yecos/archii/blob/main/src/app/HomeContent.tsx"
click node_dashboard "https://github.com/yecos/archii/blob/main/src/screens/DashboardScreen.tsx"
click node_project_screens "https://github.com/yecos/archii/blob/main/src/screens/ProjectDetailScreen.tsx"
click node_task_screen "https://github.com/yecos/archii/blob/main/src/screens/TasksScreen.tsx"
click node_field_screens "https://github.com/yecos/archii/blob/main/src/screens/WeeklyAgendaScreen.tsx"
click node_inventory "https://github.com/yecos/archii/blob/main/src/hooks/useInventory.tsx"
click node_time_tracking "https://github.com/yecos/archii/blob/main/src/hooks/useTimeTracking.tsx"
click node_app_context "https://github.com/yecos/archii/blob/main/src/contexts/AppContext.tsx"
click node_firestore_actions "https://github.com/yecos/archii/blob/main/src/lib/firestore-actions.ts"
click node_firebase_client "https://github.com/yecos/archii/blob/main/src/lib/firebase-service.ts"
click node_firebase_admin "https://github.com/yecos/archii/blob/main/src/lib/firebase-admin.ts"
click node_api_auth "https://github.com/yecos/archii/blob/main/src/lib/api-auth.ts"
click node_api_routes "https://github.com/yecos/archii/tree/main/src/app/api"
click node_ai "https://github.com/yecos/archii/tree/main/src/app/api/ai"
click node_compliance "https://github.com/yecos/archii/blob/main/src/app/api/compliance/route.ts"
click node_integrations "https://github.com/yecos/archii/tree/main/src/app/api/integrations"
click node_onedrive "https://github.com/yecos/archii/tree/main/src/app/api/onedrive"
click node_messaging "https://github.com/yecos/archii/tree/main/src/app/api/notifications"
click node_offline "https://github.com/yecos/archii/blob/main/public/sw.js"
click node_sdk_client "https://github.com/yecos/archii/blob/main/sdk/src/client.ts"
click node_sdk_webhooks "https://github.com/yecos/archii/blob/main/sdk/src/webhooks.ts"

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_auth,node_workspace,node_app_shell,node_dashboard,node_user toneBlue
class node_project_screens,node_task_screen,node_field_screens,node_inventory,node_time_tracking,node_firestore toneAmber
class node_app_context,node_firestore_actions,node_firebase_client,node_firebase_admin,node_api_auth,node_api_routes,node_ai,node_compliance toneMint
class node_integrations,node_onedrive,node_messaging,node_offline toneRose
class node_sdk_client,node_sdk_webhooks,node_firebase_auth,node_third_party toneIndigo
```

## Components

### App experience

- [Sign-in](https://github.com/yecos/archii/blob/main/src/components/layout/AuthScreen.tsx): `src/components/layout/AuthScreen.tsx`
- [Workspace selection](https://github.com/yecos/archii/blob/main/src/components/layout/TenantSelectionScreen.tsx): `src/components/layout/TenantSelectionScreen.tsx`
- [App shell](https://github.com/yecos/archii/blob/main/src/app/HomeContent.tsx): `src/app/HomeContent.tsx`
- [Dashboard and reports](https://github.com/yecos/archii/blob/main/src/screens/DashboardScreen.tsx): `src/screens/DashboardScreen.tsx`

### Project work

- [Project screens](https://github.com/yecos/archii/blob/main/src/screens/ProjectDetailScreen.tsx): `src/screens/ProjectDetailScreen.tsx`
- [Tasks and Kanban](https://github.com/yecos/archii/blob/main/src/screens/TasksScreen.tsx): `src/screens/TasksScreen.tsx`
- [Field operations](https://github.com/yecos/archii/blob/main/src/screens/WeeklyAgendaScreen.tsx): `src/screens/WeeklyAgendaScreen.tsx`
- [Inventory](https://github.com/yecos/archii/blob/main/src/hooks/useInventory.tsx): `src/hooks/useInventory.tsx`
- [Time tracking](https://github.com/yecos/archii/blob/main/src/hooks/useTimeTracking.tsx): `src/hooks/useTimeTracking.tsx`

### Platform services

- [Application state](https://github.com/yecos/archii/blob/main/src/contexts/AppContext.tsx): `src/contexts/AppContext.tsx`
- [Entity operations](https://github.com/yecos/archii/blob/main/src/lib/firestore-actions.ts): `src/lib/firestore-actions.ts`
- [Firebase client](https://github.com/yecos/archii/blob/main/src/lib/firebase-service.ts): `src/lib/firebase-service.ts`
- [Firebase Admin](https://github.com/yecos/archii/blob/main/src/lib/firebase-admin.ts): `src/lib/firebase-admin.ts`
- [API authentication](https://github.com/yecos/archii/blob/main/src/lib/api-auth.ts): `src/lib/api-auth.ts`
- [API routes](https://github.com/yecos/archii/tree/main/src/app/api): `src/app/api`
- [AI assistant and RAG](https://github.com/yecos/archii/tree/main/src/app/api/ai): `src/app/api/ai`
- [Compliance and GDPR](https://github.com/yecos/archii/blob/main/src/app/api/compliance/route.ts): `src/app/api/compliance/route.ts`

### Integrations

- [External integrations](https://github.com/yecos/archii/tree/main/src/app/api/integrations): `src/app/api/integrations`
- [OneDrive files](https://github.com/yecos/archii/tree/main/src/app/api/onedrive): `src/app/api/onedrive`
- [Notifications and WhatsApp](https://github.com/yecos/archii/tree/main/src/app/api/notifications): `src/app/api/notifications`
- [PWA and offline](https://github.com/yecos/archii/blob/main/public/sw.js): `public/sw.js`

### Public API and SDK

- [Archii SDK](https://github.com/yecos/archii/blob/main/sdk/src/client.ts): `sdk/src/client.ts`
- [Webhook SDK](https://github.com/yecos/archii/blob/main/sdk/src/webhooks.ts): `sdk/src/webhooks.ts`

### Other components

- **User**
- **Firebase Firestore**
- **Firebase Auth**
- **Third-party services**

## Connections

- User → Sign-in: signs in
- Sign-in → Workspace selection: selects workspace
- Workspace selection → App shell: opens app
- App shell → Dashboard and reports: shows screens
- App shell → Project screens: shows screens
- App shell → Tasks and Kanban: shows screens
- App shell → Field operations: shows screens
- App shell → Application state: uses state
- Application state → Firebase client: calls (evidence: `src/contexts/AppContext.tsx`)
- Application state → Entity operations: calls (evidence: `src/contexts/AppContext.tsx`)
- Firebase client → Firebase Firestore: reads and writes
- Sign-in → Firebase Auth: authenticates with
- Dashboard and reports → Time tracking: summarizes
- Dashboard and reports → Inventory: summarizes
- Tasks and Kanban → Time tracking: uses tracking (evidence: `src/screens/TasksScreen.tsx`)
- Inventory → Application state: reads context (evidence: `src/hooks/useInventory.tsx`)
- Time tracking → Application state: reads context (evidence: `src/hooks/useTimeTracking.tsx`)
- API routes → API authentication: authenticates requests (evidence: `src/app/api/admin-data/route.ts`)
- API authentication → Firebase Admin: verifies tokens (evidence: `src/lib/api-auth.ts`)
- Firebase Admin → Firebase Firestore: accesses
- API routes → Compliance and GDPR: includes
- Compliance and GDPR → API authentication: authenticates requests (evidence: `src/app/api/compliance/route.ts`)
- Compliance and GDPR → Third-party services: handles GDPR data
- App shell → AI assistant and RAG: offers AI assistant
- AI assistant and RAG → Third-party services: uses Gemini
- App shell → External integrations: offers connectors
- App shell → OneDrive files: browses files
- App shell → Notifications and WhatsApp: shows notifications
- Notifications and WhatsApp → Third-party services: sends messages
- App shell → PWA and offline: supports offline
- Archii SDK → API routes: calls API
- Webhook SDK → Third-party services: handles webhooks
