# masudrana430/web-test-masudrana430 architecture

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

- Interactive diagram: https://gitdiagram.com/masudrana430/web-test-masudrana430
- Repository: https://github.com/masudrana430/web-test-masudrana430

## Overview

1. **Monorepo shape**
   Chirp is a pnpm + Turborepo monorepo with three deployable apps and several shared packages. The major runtime boundaries are: `apps/api` for backend services, `apps/client-user` for the consumer UI, and `apps/client-admin` for moderation/admin UI.

2. **Backend core**
   The API server in `apps/api` is a gRPC service, not a REST API. Request handling is split into gRPC handlers under `src/grpc/handlers` and business logic services under `src/services`. The handlers are the transport boundary; services contain the feature logic.

3. **Contract-first service layer**
   `packages/proto` is the service contract source of truth. Proto files define services such as auth, users, posts, comments, likes, follows, bookmarks, notifications, search, and admin. Generated proto artifacts are consumed by the API and client-side gRPC code.

4. **Client-to-server flow**
   Both frontends are TanStack Start apps with server functions under `src/server/functions`. Those server functions act as the app boundary: route components call server functions, and the server functions use `packages/grpc-client` to talk to the API over gRPC. This keeps browser code off the direct backend boundary.

5. **Two separate frontends**
   `apps/client-user` is the consumer social app with routes for auth, feed, explore, posts, profiles, bookmarks, notifications, and search. `apps/client-admin` is a separate admin console focused on moderation, audits, reports, users, and post/comment management. They share the same backend and data model but have different UI and authorization surfaces.

6. **Authentication and session boundary**
   Auth is handled in the API via the auth service and in each client via server-side session helpers. The user app has login/register flows; the admin app has a stronger auth gate and admin-specific server auth logic. Session state is kept at the app/server-function layer rather than in shared client state.

7. **Domain services and data flow**
   The backend service layer is organized by domain: posts, comments, likes, follows, bookmarks, feed, notifications, search, users, mentions, and admin. Typical flows are: user action in client route -> server function -> gRPC client -> API handler -> domain service -> SQLite via Drizzle -> response back through gRPC to the app.

8. **Persistence layer**
   Persistence is SQLite, with schema definitions in `packages/db-schema` and migrations in `db/migrations`. The API owns database access through `apps/api/src/db`, and seed data is in `apps/api/src/db/seed.ts`. The database tables mirror the product domains: users, posts, comments, likes, follows, bookmarks, notifications, reports, and audit logs.

9. **Shared UI and types**
   `packages/ui` is a shared design system built with StyleX components such as Button, Card, Input, TextArea, Avatar, and loading primitives. `packages/shared-types` provides common TypeScript types for API/session data. These packages reduce duplication across both client apps.

10. **Feature-specific frontend composition**
   The user app is organized around reusable feature components like PostCard, CommentCard, FollowButton, NotificationBell, and post/comment forms. Routes are file-based and page-specific, while server functions isolate backend calls per feature. The admin app follows the same pattern but with moderation-oriented routes and layout components such as `AdminHeader`.

11. **Infra and tooling**
   Styling is managed with StyleX tokens in each app and shared UI package. TypeScript is strict and centralized with shared configs under `tooling/typescript`. Biome handles linting/formatting. Vitest covers unit tests, Playwright covers end-to-end tests, and GitHub Actions runs the test workflow.

12. **Operational boundaries**
   The README documents three local service endpoints: user app on 3000, admin app on 3002, and API on 3001 with a health check. That separation is important for a diagram: the browsers hit the two TanStack Start apps, and only those apps talk to the API backend and database indirectly through gRPC.

Main entry points: [`apps/api`](https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/api) (API), [`apps/client-user`](https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/client-user) (User app), [`apps/client-admin`](https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/client-admin) (Admin app), [`.github/workflows/test.yml`](https://github.com/masudrana430/web-test-masudrana430/blob/main/.github/workflows/test.yml) (CI workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Apps"]
  node_api["API<br/>gRPC service"]
  node_api_handlers["gRPC handlers<br/>transport"]
  node_api_services["Domain services<br/>business logic"]
  node_api_db[("DB access<br/>persistence layer")]
  node_user_app["User app<br/>TanStack Start UI"]
  node_user_funcs["Server functions<br/>app boundary"]
  node_user_routes["User routes<br/>route UI"]
  node_user_components["Feature UI<br/>components"]
  node_admin_app["Admin app<br/>TanStack Start UI"]
  node_admin_funcs["Admin functions<br/>app boundary"]
  node_admin_routes["Admin routes<br/>route UI"]
  node_admin_components["Admin UI<br/>components"]
end

subgraph group_packages["Packages"]
  node_proto["Proto contracts<br/>IDL source"]
  node_grpc_client["gRPC client<br/>client library"]
  node_db_schema[("DB schema<br/>schema package")]
  node_ui_pkg["UI kit<br/>design system"]
  node_shared_types["Shared types<br/>type package"]
end

subgraph group_infra["Infra"]
  node_migrations["Migrations"]
  node_ts_tooling["TS tooling<br/>workspace config"]
  node_ci["CI workflow<br/>GitHub Actions<br/>[test.yml]"]
end

node_user_routes -->|"calls"| node_user_funcs
node_user_funcs -->|"uses"| node_grpc_client
node_admin_routes -->|"calls"| node_admin_funcs
node_admin_funcs -->|"uses"| node_grpc_client
node_grpc_client -->|"typed by"| node_proto
node_api_handlers -->|"implements"| node_proto
node_api_handlers -->|"delegates"| node_api_services
node_api_services -->|"persists"| node_api_db
node_api_db -->|"uses"| node_db_schema
node_db_schema -->|"evolves into"| node_migrations
node_user_app -->|"renders with"| node_ui_pkg
node_admin_app -->|"renders with"| node_ui_pkg
node_user_app -->|"shares types"| node_shared_types
node_admin_app -->|"shares types"| node_shared_types
node_api -->|"hosts"| node_api_handlers
node_api -->|"contains"| node_api_services
node_api -->|"owns"| node_api_db
node_user_app -->|"calls via gRPC"| node_api
node_admin_app -->|"calls via gRPC"| node_api
node_ci -.->|"tests"| node_user_app
node_ci -.->|"tests"| node_admin_app
node_ci -.->|"tests"| node_api

click node_api "https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/api"
click node_api_handlers "https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/api/src/grpc/handlers"
click node_api_services "https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/api/src/services"
click node_api_db "https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/api/src/db"
click node_user_app "https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/client-user"
click node_user_funcs "https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/client-user/src/server/functions"
click node_user_routes "https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/client-user/src/routes"
click node_user_components "https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/client-user/src/components"
click node_admin_app "https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/client-admin"
click node_admin_funcs "https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/client-admin/src/server/functions"
click node_admin_routes "https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/client-admin/src/routes"
click node_admin_components "https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/client-admin/src/components"
click node_proto "https://github.com/masudrana430/web-test-masudrana430/tree/main/packages/proto"
click node_grpc_client "https://github.com/masudrana430/web-test-masudrana430/tree/main/packages/grpc-client"
click node_db_schema "https://github.com/masudrana430/web-test-masudrana430/tree/main/packages/db-schema"
click node_ui_pkg "https://github.com/masudrana430/web-test-masudrana430/tree/main/packages/ui"
click node_shared_types "https://github.com/masudrana430/web-test-masudrana430/tree/main/packages/shared-types"
click node_migrations "https://github.com/masudrana430/web-test-masudrana430/tree/main/db/migrations"
click node_ts_tooling "https://github.com/masudrana430/web-test-masudrana430/tree/main/tooling/typescript"
click node_ci "https://github.com/masudrana430/web-test-masudrana430/blob/main/.github/workflows/test.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_api,node_api_handlers,node_api_services,node_api_db,node_user_app,node_user_funcs,node_user_routes,node_user_components,node_admin_app,node_admin_funcs,node_admin_routes,node_admin_components toneBlue
class node_proto,node_grpc_client,node_db_schema,node_ui_pkg,node_shared_types toneAmber
class node_migrations,node_ts_tooling,node_ci toneMint
```

## Components

### Apps

Deployable API and client runtimes

- [API](https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/api): gRPC service · Backend runtime for auth, social domains, and admin operations · `apps/api`
- [gRPC handlers](https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/api/src/grpc/handlers): transport · Service entrypoints that map proto requests into backend operations · `apps/api/src/grpc/handlers`
- [Domain services](https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/api/src/services): business logic · Feature logic for auth, posts, comments, feed, search, and moderation · `apps/api/src/services`
- [DB access](https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/api/src/db): persistence layer · Database access and seeding owned by the API · `apps/api/src/db`
- [User app](https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/client-user): TanStack Start UI · Consumer social frontend for browsing, posting, and discovery · `apps/client-user`
- [Server functions](https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/client-user/src/server/functions): app boundary · Server-side feature functions that call the API through gRPC · `apps/client-user/src/server/functions`
- [User routes](https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/client-user/src/routes): route UI · File-based pages for auth, feed, posts, profiles, bookmarks, notifications, and search · `apps/client-user/src/routes`
- [Feature UI](https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/client-user/src/components): components · Reusable social UI such as posts, comments, follows, notifications, and shared primitives · `apps/client-user/src/components`
- [Admin app](https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/client-admin): TanStack Start UI · Moderation console for audits, reports, users, and content management · `apps/client-admin`
- [Admin functions](https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/client-admin/src/server/functions): app boundary · Server-side auth and admin feature calls into the API · `apps/client-admin/src/server/functions`
- [Admin routes](https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/client-admin/src/routes): route UI · Moderation-focused pages for login, audit, reports, users, posts, and comments · `apps/client-admin/src/routes`
- [Admin UI](https://github.com/masudrana430/web-test-masudrana430/tree/main/apps/client-admin/src/components): components · Admin layout and shared console components · `apps/client-admin/src/components`

### Packages

Shared contracts, UI, and client libraries

- [Proto contracts](https://github.com/masudrana430/web-test-masudrana430/tree/main/packages/proto): IDL source · Service definitions and generated contract surface for API and clients · `packages/proto`
- [gRPC client](https://github.com/masudrana430/web-test-masudrana430/tree/main/packages/grpc-client): client library · Shared client used by both frontends to call the API · `packages/grpc-client`
- [DB schema](https://github.com/masudrana430/web-test-masudrana430/tree/main/packages/db-schema): schema package · Shared Drizzle schema for SQLite tables and relations · `packages/db-schema`
- [UI kit](https://github.com/masudrana430/web-test-masudrana430/tree/main/packages/ui): design system · Shared StyleX components and tokens · `packages/ui`
- [Shared types](https://github.com/masudrana430/web-test-masudrana430/tree/main/packages/shared-types): type package · Common API and session TypeScript types · `packages/shared-types`

### Infra

Database, migrations, and tooling

- [Migrations](https://github.com/masudrana430/web-test-masudrana430/tree/main/db/migrations): sqlite migrations · Database migration history for the shared schema · `db/migrations`
- [TS tooling](https://github.com/masudrana430/web-test-masudrana430/tree/main/tooling/typescript): workspace config · Shared TypeScript base and React configs · `tooling/typescript`
- [CI workflow](https://github.com/masudrana430/web-test-masudrana430/blob/main/.github/workflows/test.yml): GitHub Actions · Repository test workflow · `.github/workflows/test.yml`

## Connections

- User routes → Server functions: calls · Route components invoke server functions
- Server functions → gRPC client: uses · Client app functions call the shared gRPC client
- Admin routes → Admin functions: calls · Admin pages invoke server functions
- Admin functions → gRPC client: uses · Admin functions call the shared gRPC client
- gRPC client → Proto contracts: typed by · Client stubs are generated from service contracts
- gRPC handlers → Proto contracts: implements · Handlers realize the contract-defined services
- gRPC handlers → Domain services: delegates · Transport layer forwards into domain logic
- Domain services → DB access: persists · Services read and write through the API-owned database layer
- DB access → DB schema: uses · Database layer is shaped by the shared schema package
- DB schema → Migrations: evolves into · Schema changes are captured in migration files
- User app → UI kit: renders with · Consumer frontend uses shared design system components
- Admin app → UI kit: renders with · Admin frontend uses shared design system components
- User app → Shared types: shares types · User app consumes common API and session types
- Admin app → Shared types: shares types · Admin app consumes common API and session types
- API → gRPC handlers: hosts · API runtime exposes gRPC handlers
- API → Domain services: contains · API runtime includes the domain service layer
- API → DB access: owns · API runtime owns database access
- User app → API: calls via gRPC · Browser flows reach the backend only through server functions and the client library
- Admin app → API: calls via gRPC · Admin flows reach the backend only through server functions and the client library
- CI workflow → User app: tests · Workflow exercises the user app
- CI workflow → Admin app: tests · Workflow exercises the admin app
- CI workflow → API: tests · Workflow exercises the API runtime