You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+5-2Lines changed: 5 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -15,6 +15,8 @@ The server is responsible for:
15
15
- notifications, analytics, and moderation workflows
16
16
- access checks for gated off-chain content
17
17
18
+
See [Backend Domain Model and Endpoint Boundaries](./docs/architecture/domain-boundaries.md) for a technical overview and [API Versioning](./docs/api-versioning.md) for details on schema versioning.
19
+
18
20
## Tech
19
21
20
22
- Node.js
@@ -167,7 +169,8 @@ readinessProbe:
167
169
168
170
## Open source workflow
169
171
170
-
- Read [CONTRIBUTING.md](./CONTRIBUTING.md) before starting work.
171
-
- Browse the maintainer issue inventory in [docs/open-source/issue-backlog.md](./docs/open-source/issue-backlog.md).
172
+
- Read the [README](./README.md) for context.
173
+
- Review the [Backend Domain Model and Endpoint Boundaries](./docs/architecture/domain-boundaries.md).
174
+
- Review the scoped backlog in [docs/open-source/issue-backlog.md](./docs/open-source/issue-backlog.md).
172
175
- Review [SECURITY.md](./SECURITY.md) before reporting vulnerabilities.
173
176
- Use the issue templates in [`.github/ISSUE_TEMPLATE`](./.github/ISSUE_TEMPLATE) for new scoped work.
The Access Layer Server uses versioning headers to inform clients about the current API version and the expected structure of request bodies.
4
+
5
+
## Response Headers
6
+
7
+
### `X-API-Version`
8
+
9
+
Indicates the current overall version of the API. This is typically used for tracking feature sets and major API releases.
10
+
11
+
### `X-Schema-Version`
12
+
13
+
Indicates the active version of the request body schema. This version should be checked by consumers to ensure they are sending request bodies in the format expected by the server.
14
+
15
+
## Versioning Strategy
16
+
17
+
Both headers follow [Semantic Versioning (SemVer)](https://semver.org/):
18
+
19
+
-**MAJOR** version: Breaking changes to the API or schema.
20
+
-**MINOR** version: Backwards-compatible new features or additions.
1.**Check Headers**: Consumers should inspect the `X-Schema-Version` header in API responses.
26
+
2.**Schema Alignment**: If the `X-Schema-Version` major version changes, consumers must update their request body structures to match the new schema requirements.
27
+
3.**Warning Handling**: Consumers may choose to log warnings if they detect a version mismatch that they haven't yet updated to support.
This document outlines the core backend entities, their relationships, and the boundaries between different modules in the Access Layer Server.
4
+
5
+
## Domain Model
6
+
7
+
The following diagram illustrates the core entities and their relationships within the system:
8
+
9
+
```mermaid
10
+
erDiagram
11
+
User ||--o| CreatorProfile : "owns"
12
+
User ||--o| StellarWallet : "links"
13
+
User {
14
+
string id PK
15
+
string email
16
+
string passwordHash
17
+
string firstName
18
+
string lastName
19
+
boolean emailVerified
20
+
}
21
+
CreatorProfile {
22
+
string id PK
23
+
string userId FK
24
+
string handle
25
+
string displayName
26
+
string bio
27
+
json perks
28
+
}
29
+
StellarWallet {
30
+
string id PK
31
+
string userId FK
32
+
string address
33
+
}
34
+
IndexerDLQ {
35
+
string id PK
36
+
string jobType
37
+
json payload
38
+
string failureReason
39
+
}
40
+
AuditEvent {
41
+
string id PK
42
+
string actor
43
+
string action
44
+
string target
45
+
string targetId
46
+
json metadata
47
+
}
48
+
```
49
+
50
+
### Core Entities
51
+
52
+
1.**User**: Represents a registered user. Holds authentication and basic profile data.
53
+
2.**CreatorProfile**: Represents the creator persona of a user. Tied to a specific handle and contains metadata like bio and perks.
54
+
3.**StellarWallet**: Links a user to their Stellar public address. Used for identity verification and ownership checks.
55
+
4.**IndexerDLQ**: Stores failed indexing jobs from the Stellar blockchain for manual review or reprocessing.
56
+
5.**AuditEvent**: A generic log for significant actions occurring in the system.
57
+
58
+
## Module Boundaries
59
+
60
+
The server is organized into feature-based modules under `src/modules/`. Each module is responsible for its own business logic, routes, and (where applicable) data validation.
|`auth`| User registration, login, session management, and password resets. |`User`|
67
+
|`creators`| Public and private creator profile management, including stats and discovery. |`CreatorProfile`|
68
+
|`wallet`| Linking and verifying Stellar wallets. |`StellarWallet`|
69
+
|`admin`| Internal management tools and system monitoring. | All |
70
+
|`health`| System health checks and status monitoring. | N/A |
71
+
72
+
### Cross-Module Rules
73
+
74
+
To ensure a maintainable and decoupled architecture, the following rules apply:
75
+
76
+
1.**No Direct Database Access**: Modules should not directly query Prisma models belonging to other modules if a service/utility exists.
77
+
2.**Shared Utilities**: Common logic (e.g., mail sending, logging, pagination) belongs in `src/utils/` and can be used by any module.
78
+
3.**Constants**: Shared configuration and string constants belong in `src/constants/`.
79
+
4.**Types**: Cross-cutting TypeScript types belong in `src/types/`.
80
+
81
+
### Interaction Patterns
82
+
83
+
-**Initialization**: `src/app.ts` assembles the modules and registers global middlewares.
84
+
-**Data Sharing**: If a module needs data from another (e.g., `creators` needing user info), it should use the Prisma client (which is shared) but respect the logical boundaries defined in the schema files.
The indexer processes events from the blockchain to update the read models and activity feeds. To ensure data consistency and prevent duplicate processing, the following strategies are employed.
4
+
5
+
## 1. Deduplication
6
+
7
+
Before processing a batch of events, they should be deduped based on their unique identifier on the chain: `transactionHash` and `eventIndex`.
8
+
9
+
The `dedupeChainEvents` helper in `src/utils/indexer-dedupe.utils.ts` provides this functionality.
Event handlers must be idempotent. This means that processing the same event multiple times should have the same effect as processing it once.
24
+
25
+
### Strategies for Idempotency:
26
+
27
+
-**Database Upserts**: Use Prisma's `upsert` or `update` with unique constraints where possible.
28
+
-**State Check**: Before applying a change (like incrementing a balance), verify if the event has already been accounted for (e.g. by checking a `lastProcessedLedger` or a specific event log).
29
+
-**Atomic Transactions**: Ensure that all changes related to an event are committed in a single database transaction.
30
+
31
+
## 3. Error Handling
32
+
33
+
If an event fails to process after multiple retries, it is moved to the [Dead-Letter Queue (DLQ)](./DLQ_WORKFLOW.md) for manual investigation.
The script must process records in batches (recommended batch size: 500) and log progress at each checkpoint.
60
63
61
64
4.**Verify output:**
65
+
62
66
```sql
63
67
SELECTCOUNT(*) FROM creator_ownership_reads;
64
68
-- Compare to expected count derived from source tables
65
69
```
70
+
66
71
Spot-check a sample of records against the source of truth.
67
72
68
73
5.**Resume the live indexer.** If fenced, lift the fence. If the indexer was paused, restart it and confirm it picks up from the correct cursor position.
69
74
70
75
## Expected duration
71
76
72
-
| Table size | Estimated rebuild time |
73
-
|---|---|
74
-
| < 10k rows | < 1 minute |
75
-
| 10k – 100k rows | 2–10 minutes |
76
-
| 100k – 1M rows | 15–60 minutes |
77
-
| > 1M rows | Plan for multi-hour window; use batched pagination |
0 commit comments